Contributing

Branching

• Feature branches off develop (default branch).
• PR against develop using docs/pull_request_template.md.
• Squash-merge; commit message follows the repo's [TAG] [FEAT/FIX/TECH/CHORE] convention (see git log).

CI/CD

Config in .circleci/:

1. generate-deploy-config — diffs HEAD vs HEAD^1, computes changed services/*, emits continuation workflow. FORCE_ALL=true deploys everything.
2. test — unit/integration on PRs.
3. deploy — serverless deploy per changed service to the target stage.

libs/* changes trigger deploy of all services (shared workspace deps). See CI/CD.

Manual deploy

From inside a service folder:

yarn g:deploy           # dev
yarn g:deploy:staging   # staging
yarn g:deploy:prod      # prod (aws-drive-prod-admin)

g:deploy = sls deploy -c ./serverless.yml --stage <stage> --region ap-southeast-2. Prune with yarn g:prune (5 dev/staging, 10 prod).

Conventions

• TypeScript; esbuild bundles each function individually (package.individually: true).
• Shared logic in libs/, not duplicated across services.
• New env vars in serverless.common.yml provider.environment (shared) or service environment (service-specific).
• Secrets from SSM (ssm:/shared/drive/...) or Secrets Manager via the Parameters-and-Secrets extension (port 2773). Never hard-coded.

Docs

docs/site/ (standalone package). To add/edit a page:

1. Create/edit pages/<section>/<slug>.mdx.
2. Register in lib/sections.ts (PAGES_BY_SECTION).
3. New service: node scripts/init-service-docs.mjs <service> to scaffold, then author openapi/<service>.yaml.
4. yarn build — validates OpenAPI specs + cross-checks paths vs serverless.yml.

See docs/site/DOCS_GUIDELINES.md.