docs: define phased backend roadmap and engineering standards

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+coverage/
+.env
+.env.*
+!.env.example
+src/generated/
+*.log

README.md

@@ -0,0 +1,29 @@
+# Mani Candles backend
+
+Phase 1A implements the service foundation. It does not yet expose commerce or identity APIs.
+
+## Setup
+
+Use Node 24 LTS and pnpm 11.19.0. Copy `.env.example` to `.env` and set a PostgreSQL connection URL. Never commit credentials.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm db:generate
+pnpm db:deploy
+pnpm check
+pnpm build
+pnpm start
+```
+
+Development: run `pnpm dev` to compile on changes and `pnpm start:watch` in a second terminal after the first compilation. HTTP endpoints: `GET /api/v1/health/live` and `GET /api/v1/health/ready`. Readiness returns 503 when the database query fails. Health responses deliberately omit infrastructure details.
+
+## Layout
+
+- `src/config`: validated configuration, injected once.
+- `src/database`: Prisma connection lifecycle and database probes.
+- `src/health`: controller and application service.
+- `prisma/migrations`: ordered, committed SQL migrations.
+- `test`: configuration, lifecycle, and HTTP tests.
+- `docs`: delivery roadmap and engineering workflow.
+
+Production must use a managed secret store, TLS termination, a restricted database account, backups, and the deployment migration command. Do not expose this foundation as a completed commerce platform.

docs/engineering.md

@@ -0,0 +1,11 @@
+# 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.

docs/roadmap.md

@@ -0,0 +1,35 @@
+# Delivery roadmap
+
+Source: Mani Candles Commerce Platform specification and project pack created in the earlier project discussion. Stack: modular NestJS/TypeScript application, PostgreSQL/Prisma, with Redis workers and private object storage introduced when needed. Provider adapters isolate external integrations.
+
+## Phase 1: Foundation and core commerce
+
+- 1A: service bootstrap, configuration, database lifecycle, initial organization migration, health API, test/build baseline, team workflow.
+- 1B: authentication, sessions, recovery, users, configurable RBAC, organization access, approval status, audit events. Test denied access and cross-organization access.
+- 1C: catalog, variants, collections, addresses, inventory ledger and reservations. Test concurrent reservation and stock reconciliation.
+- 1D: cart, checkout, orders, coupons and pricing snapshots. Test money precision, discount eligibility, retries and transaction rollback.
+- 1E: verified payments/refunds, shipping/tracking, returns, notifications and operational dashboard. Test signatures, replay, partial fulfillment and reconciliation.
+
+## Phase 2: Internal operations
+
+Suppliers, material/urli classification and compatibility, procurement, purchase orders, partial goods receipts, QC, invoices, supplier payments, private versioned documents and validation, BOM, production batches, consumption, wastage, packaging BOM and costing.
+
+## Phase 3: B2B and white label
+
+Business verification, price lists, MOQ, quotations, credit policies, samples, branding/artwork approvals, partner purchase orders, partial payments, custom candle requests and partner reporting.
+
+## Phase 4: Growth channels
+
+Wishlist, verified reviews/moderation, seasonal campaigns, discounts, cart recovery, consent-aware messaging, Instagram, Etsy, WhatsApp, blogs/SEO and segmentation.
+
+## Phase 5: Community and optimization
+
+Moderated forums, advanced analytics, forecasts, accounting adapters, profitability and workflow automation. SaaS tenancy/billing requires a separate architecture decision before implementation; an organization table alone does not provide tenant isolation.
+
+## Definition of done for every feature
+
+Small cohesive files; no duplicated business rules; unit tests for success, failure and boundaries; HTTP/integration tests where behavior crosses boundaries; schema migration and upgrade validation when persistence changes; documented API and permission contract; passing checks; focused Conventional Commit; reviewed pull request. Do not mark an entire phase complete until its end-to-end acceptance criteria pass.
+
+## Decisions still needed
+
+Git author identity; remote connectivity; provider accounts; deployment target and PostgreSQL service; tax/invoice and retention rules; stock location model; approval thresholds; Etsy sync direction; launch feature cut. Resolve each before its dependent milestone.

docs/verification.md

@@ -0,0 +1,7 @@
+# Verification record
+
+Phase 1A: 19 tests pass across configuration, database lifecycle, and HTTP health/security behavior. Formatting, Prisma schema validation, TypeScript checking and production compilation pass. Coverage excludes generated client, module declarations and bootstrap: 100% statements/lines/functions, 85.71% branches.
+
+Tests use mocked database connectivity. A real PostgreSQL instance is not installed/configured in this workspace. Run `node scripts/verify-migrations.mjs` with DATABASE_URL pointing to a disposable PostgreSQL database; it applies migrations, checks status and checks schema drift. Repeat against a restored prior-release snapshot for future releases. This script applies migrations and must never target an unapproved production database.
+
+SSH remote access failed host-key verification. No remote history was fetched and no commits were pushed. The feature branch is provisional until remote history is checked. Git author is configured locally as mihir <motiyanimihir@gmail.com>. Do not merge an unrelated root history into an existing repository; fetch and base the feature work on its default branch first.