manicanldes-backend/docs/engineering.md

Team engineering workflow

Use backend as its own repository. Base short-lived feat/<feature> and fix/<issue> branches on the verified remote default branch. Inspect status, fetch and fast-forward the base before starting; do not reset or overwrite collaborators' work. Open a pull request for each independently reviewable feature. Require CI and review before merging. Never force-push a shared branch.

Use Conventional Commits, for example feat(health): add database readiness checks. Commit each completed feature and each subsequent fix separately. Stage explicit files, inspect the staged diff, and keep secrets/generated files out of Git. Push feature branches with upstream tracking; do not push directly to the default branch. Configure repository-local author identity using the developer's supplied name/email.

Controllers translate HTTP; services own use cases; repositories own persistence. Export narrow module interfaces. Extract shared behavior only when it has a real second use. Aim for source files under 200 lines, splitting by responsibility. Keep names explicit and avoid speculative frameworks.

For schema changes, run pnpm db:migrate --name descriptive_change against a disposable development database. Review generated SQL and commit it with the feature. Never edit an applied migration or use db push in production. Use expand/backfill/contract for destructive changes; back up and test recovery before deployment. Apply pnpm db:deploy once in the release pipeline, then verify migration status and readiness. Test migrations from an empty database and the prior release snapshot.

Money uses exact decimal or minor units with explicit currency. Inventory uses ledger entries and transactions. Orders, payments and shipments have separate states. External writes need idempotency and authenticated webhooks. Private documents require authorization and isolated processing. These rules are implemented and tested within the corresponding milestones. See append-only migration workflow for timestamp names and checksum recording.