TBBN.Merchant Platform docs
Roadmapdocs/phase-plan/phase-0-3-build-plan.md

Phase 0-3 Build Plan (this scaffold's working core)

Historical scope note: this doc describes the plan for the very first build pass (Phase 0-3 only). Everything through Phase 20 is now WORKING — see docs/phase-plan/roadmap.md's "Current status vs. what's still ahead" and docs/architecture/service-catalog.md for the up-to-date picture. The local dev topology described below (no Kubernetes, plain Node processes, gateway reverse-proxy, Docker only for infra) still holds for the whole repo, not just Phase 0-3 — that part of this doc remains current.

Scope

Repo foundation + tooling (Phase 0), API gateway + auth (Phase 1), merchant onboarding/RBAC/API keys (Phase 2), seller identity federation (Phase 3) — implemented with real logic, not stubs, in the very first build pass. (Everything else has since graduated to WORKING too — see the note above.)

Local dev topology

No Kubernetes, no container orchestration for application code. Each Phase 0-3 service is its own NestJS process on its own port; api-gateway reverse-proxies to them. Only infra dependencies (Postgres, Redis, OpenSearch, MinIO) run in Docker via infra/docker/docker-compose.dev.yml — with a documented native-install fallback since Docker Desktop isn't confirmed installed on this machine.

PortService
3000services/api-gateway
3001services/auth-service
3002services/merchant-service
3003services/seller-identity-service
3004services/event-service
4000apps/docs-site
3100apps/merchant-dashboard
3200apps/exchange-web
5432Postgres (docker-compose)
6379Redis (docker-compose)
9200OpenSearch (docker-compose)
9000MinIO (docker-compose)

Build order actually followed in this scaffold

  1. Root tooling (package.json workspaces, tsconfig.base.json, lint/format/commit hooks).
  2. docs/ — business model, conflicts, pricing, architecture, API, security, legal flags, roadmap — written before code so every service's README can correctly reference the resolved logic instead of drifting from it.
  3. packages/db-schema — Prisma schema for all Phase 0-3 tables plus the Phase 4-10 core tables (listings/offers/trade-sessions/etc.) that are cheap to define now and expensive later.
  4. packages/types, utils, config, event-contracts, core-auth — shared code the working services depend on, built before the services themselves.
  5. packages/openapi-spec — Phase 0-3 resources fully specified.
  6. services/auth-service, services/merchant-service, services/seller-identity-service, services/event-service, services/api-gateway — in this order, since each depends on the previous (gateway last, since it routes to all the others).
  7. packages/sdk-js, packages/sdk-typescript — generated/hand-ergonomic clients over the now- real Phase 0-3 API surface.
  8. Every remaining apps/*, services/*, packages/* folder — generated as STUBs via tools/scripts/new-service.js so the full target architecture is visible and individually runnable, without pretending business logic exists where it doesn't.
  9. infra/, tools/ — compose file, env examples, codegen/seed scripts.
  10. Install, build, migrate, seed, verify the federation flow end-to-end, report status.

Definition of done for "WORKING" in this pass

A service is WORKING if: it boots, its documented endpoints exist and return real data backed by Postgres (not mocks), the specific business rules called out in docs/business/conflict-resolution-log.md that apply to it are actually enforced (e.g. seller-identity-service really does require sequential email-then-phone OTP before linking, not just an email check), and it has at least one test exercising its core flow.