1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220# 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
```bash
git clone https://github.com/equalifyEverything/equalify.git
cd equalify
```
### Install Dependencies
The project uses Yarn workspaces:
```bash
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
```bash
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:
1. Make code changes
2. Deploy to staging: `yarn build:staging`
3. Test via staging frontend or API calls
### Testing Changes
1. Create a feature branch
2. Make and test changes locally
3. Deploy to staging environment
4. Verify functionality works correctly
5. 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**: UPPER_SNAKE_CASE
### 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
1. Create handler in appropriate route folder:
```typescript
// apps/backend/routes/auth/myFeature.ts
import { db, event } from '#src/utils';
export const myFeature = async () => {
// Implementation
};
```
2. Export from route index:
```typescript
// apps/backend/routes/auth/index.ts
export { myFeature } from './myFeature';
```
3. The router automatically maps the export name to the endpoint.
### Adding a Frontend Page
1. Create page component:
```typescript
// apps/frontend/src/routes/MyPage.tsx
export const MyPage = () => {
return <div>My Page</div>;
};
```
2. Export from routes index:
```typescript
// apps/frontend/src/routes/index.ts
export { MyPage } from './MyPage';
```
3. Add route in App.tsx router configuration.
### Adding a New Scanner
1. Create service directory in `services/`
2. Implement SQS message handler
3. Create result converter in `shared/convertors/`
4. Add queue routing in `aws-lambda-scan-sqs-router`
5. 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
1. **Fork** the repository
2. **Create** a feature branch: `git checkout -b feature/my-feature`
3. **Commit** your changes with clear messages
4. **Push** to your fork
5. **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
- GitHub Issues for technical questions
- Subscribe to newsletter: [it.uic.edu/accessibility/engineering](http://it.uic.edu/accessibility/engineering)
## License
Equalify is licensed under AGPL-3.0. Contributions are subject to the same license.
---
*For architecture details, see the Architecture Overview.*