Contributing Guide
How to contribute to Staffora. We welcome bug reports, feature requests, and pull requests.
Getting Started
Follow these steps to set up your development environment and submit your first contribution.
Fork the repository
Click the Fork button on GitHub to create your own copy.
Clone your fork
git clone https://github.com/YOUR_USERNAME/staffora.git
Install dependencies
bun install
Create a feature branch
git checkout -b feature/my-feature
Start the dev environment
docker compose up -d
Make your changes
Follow the code style and module architecture described below.
Run tests
bun test
Commit and push
git push origin feature/my-feature
Open a Pull Request
Submit your PR on GitHub. All CI checks must pass before merge.
Project Structure Overview
A high-level view of the monorepo layout.
packages/
├── api/ → Backend (Elysia.js)
├── web/ → Frontend (React)
└── shared/ → Shared types, schemas, state machines
migrations/ → PostgreSQL SQL migrations
docker/ → Docker Compose + configs
Docs/ → Architecture & guides
tests/ → Integration tests Code Style
Conventions and patterns used throughout the codebase.
TypeScript Throughout
Strict mode enabled. Full type coverage across API, frontend, and shared packages.
No ORM -- Raw SQL
Tagged template literals for SQL queries. Direct PostgreSQL access for maximum control.
TypeBox + Zod Schemas
TypeBox for API validation, Zod schemas in the shared package for cross-platform use.
Tailwind CSS + React Hook Form
Tailwind for styling, React Hook Form for forms, TanStack Query for data fetching.
Module Architecture
Every API module follows this consistent pattern.
modules/feature-name/
├── routes.ts → HTTP handlers + route definitions
├── service.ts → Business logic
├── repository.ts → SQL queries (tagged templates)
├── schemas.ts → TypeBox request/response schemas
└── index.ts → Module exports routes.ts
Defines HTTP endpoints, wires validation schemas to handlers, and calls service functions.
service.ts
Contains business logic, state machine transitions, and orchestrates repository calls.
repository.ts
Raw SQL queries using tagged templates. All database access goes through here.
schemas.ts
TypeBox schemas for request body, query params, and response shapes.
index.ts
Re-exports the module's public API for use by the app router.
Testing
Comprehensive test coverage across all layers of the application.
Backend
bun test
Unit, integration, e2e, security, performance, and chaos tests.
Frontend
bun run --cwd packages/web test
Component tests, hook tests, and library tests with Vitest.
Shared
bun test
State machine tests and utility tests.
Storybook
bun run --cwd packages/web storybook
Component visual testing and development.
Adding a New API Module
Step-by-step guide to adding a new feature module to the API.
Create module directory
Create a new directory under packages/api/src/modules/your-module/
Create module files
Add routes.ts, service.ts, repository.ts, schemas.ts, index.ts
Write migration
Add a SQL migration in migrations/ with a sequential number.
Mount routes
Register your routes in packages/api/src/app.ts
Add permission entries
Define RBAC permissions for your module's endpoints.
Write tests
Add unit and integration tests for your module.
Add frontend route/components
Create the corresponding UI in packages/web/app/routes/
Pull Request Guidelines
Keep your PRs focused, tested, and well-documented.
Keep PRs focused
Each PR should address a single change or feature.
Include tests
New features must have accompanying tests.
Follow existing patterns
Match the module architecture and code style conventions.
Update documentation
If your change affects behavior, update the relevant docs.
All CI checks must pass
Lint, type checks, tests, and security scans must all succeed before merge.
CI/CD Pipelines
8 GitHub Actions workflows run automatically on every PR and push.
PR Check
Lint + type check
Tests
Unit + integration
Security Scanning
Vulnerability checks
Deployment
Automated deploy
Release
Version management