Start with the boundary
Before editing, identify whether the change belongs to shared domain types, a server application service, an infrastructure adapter, an HTTP route, the frontend client contract, or the website. Keep dependencies pointed inward and avoid making a route own business rules.
Local workflow
pnpm install
pnpm typecheck
pnpm test
pnpm --dir frontend lint
pnpm --dir frontend test:e2e
pnpm --dir site buildMake one logical change at a time. Add or update tests with the change, keep migrations explicit, and verify generated output is not accidentally committed.
Quality bar
- External input is validated with Zod at the boundary.
- Repositories own persistence; routes do not contain raw SQL.
- Application services own use-case decisions and side effects.
- Exported APIs are typed, documented, and intentionally small.
- Errors are handled with stable codes and actionable context.
- UI changes include loading, empty, error, responsive, and keyboard states.
Testing strategy
Use unit tests for domain rules and pure services, integration tests for repositories and routes, browser tests for critical user journeys, and production-like smoke checks for health and deployment. A green test is useful only when it covers the failure mode the change could introduce.
Breaking changes
This project prioritizes a clean architecture over indefinite compatibility. When a breaking change simplifies boundaries, document the migration, update all first-party callers, and remove the old path rather than carrying a permanent compatibility shim.
Review checklist
- Can a new maintainer explain the dependency direction?
- Is the smallest cohesive abstraction being changed?
- Are failure paths and authorization boundaries tested?
- Are docs, configuration, migrations, and API contracts synchronized?
- Can the change be reverted or rolled forward safely?