Back to Equalify Dashboard

Contributing Guide

Edit on GitHub

Contributing to Equalify

Equalify is an open-source project under the AGPL license. We welcome contributions from the community!

Getting Started

Prerequisites

  • Node.js 18+
  • Yarn (v1)
  • AWS CLI v2 (for deployment)
  • Git

Clone the Repository

git clone https://github.com/equalifyEverything/equalify.git
cd equalify

Install Dependencies

The project uses Yarn workspaces:

yarn install

This installs dependencies for all workspaces:

  • apps/frontend
  • apps/backend
  • services/aws-lambda-scan-html
  • services/aws-lambda-scan-pdf
  • services/aws-lambda-scan-sqs-router
  • shared/types

Development Workflow

Frontend Development

cd apps/frontend
yarn start:staging

This starts Vite dev server at http://localhost:5173 connected to staging APIs.

Backend Development

The backend runs on AWS Lambda, so local development requires:

  • Make code changes
  • Deploy to staging: yarn build:staging
  • Test via staging frontend or API calls

Testing Changes

  • Create a feature branch
  • Make and test changes locally
  • Deploy to staging environment
  • Verify functionality works correctly
  • Submit a pull request

Project Structure

equalify/
├── apps/
│   ├── backend/          # API Lambda
│   │   ├── routes/       # API endpoints
│   │   │   ├── auth/     # Authenticated endpoints
│   │   │   ├── public/   # Public endpoints
│   │   │   ├── internal/ # Internal endpoints
│   │   │   └── scheduled/# Scheduled tasks
│   │   └── utils/        # Shared utilities
│   └── frontend/         # React application
│       └── src/
│           ├── components/
│           ├── routes/
│           ├── queries/
│           └── hooks/
├── services/             # Scanning microservices
│   ├── aws-lambda-scan-sqs-router/
│   ├── aws-lambda-scan-html/
│   ├── aws-lambda-scan-pdf/
│   └── aws-lambda-verapdf-interface/
└── shared/               # Shared code
    ├── types/            # TypeScript types
    └── convertors/       # Result converters

Code Style

TypeScript

  • Use TypeScript for all new code
  • Enable strict mode
  • Use explicit types for function parameters and return values

Naming Conventions

  • Files: camelCase for utilities, PascalCase for components
  • Functions: camelCase
  • Components: PascalCase
  • Constants: UPPERSNAKECASE

Frontend Guidelines

  • Use functional components with hooks
  • Use SCSS Modules for styling
  • Use Radix UI primitives for accessible components
  • Follow React 19 best practices

Backend Guidelines

  • Keep route handlers focused and small
  • Use utility functions for shared logic
  • Always clean up database connections
  • Handle errors gracefully with appropriate status codes

Adding New Features

Adding an API Endpoint

  • Create handler in appropriate route folder:
// apps/backend/routes/auth/myFeature.ts
   import { db, event } from '#src/utils';
   
   export const myFeature = async () => {
     // Implementation
   };

  • Export from route index:
// apps/backend/routes/auth/index.ts
   export { myFeature } from './myFeature';

  • The router automatically maps the export name to the endpoint.

Adding a Frontend Page

  • Create page component:
// apps/frontend/src/routes/MyPage.tsx
   export const MyPage = () => {
     return <div>My Page</div>;
   };

  • Export from routes index:
// apps/frontend/src/routes/index.ts
   export { MyPage } from './MyPage';

  • Add route in App.tsx router configuration.

Adding a New Scanner

  • Create service directory in services/
  • Implement SQS message handler
  • Create result converter in shared/convertors/
  • Add queue routing in aws-lambda-scan-sqs-router
  • Update type definitions in shared/types/

Accessibility Requirements

As an accessibility tool, Equalify must meet high accessibility standards:

  • All features must be keyboard navigable
  • Use semantic HTML elements
  • Include proper ARIA attributes where needed
  • Ensure sufficient color contrast
  • Test with screen readers
  • Follow WCAG 2.1 AA guidelines

Pull Request Process

  • Fork the repository
  • Create a feature branch: git checkout -b feature/my-feature
  • Commit your changes with clear messages
  • Push to your fork
  • Open a pull request against main

PR Requirements

  • Clear description of changes
  • Tests pass (if applicable)
  • No accessibility regressions
  • Code follows project style
  • Documentation updated if needed

Reporting Issues

Use GitHub Issues for:

  • Bug reports
  • Feature requests
  • Documentation improvements
Include:
  • Clear description
  • Steps to reproduce (for bugs)
  • Expected vs actual behavior
  • Environment details

Getting Help

License

Equalify is licensed under AGPL-3.0. Contributions are subject to the same license.

For architecture details, see the Architecture Overview.