Developer onboarding

You can be productive in NestJS and still break PointNXT by emitting an order event in-process, forgetting a tenancy classification, or starting only the API. Follow this path before you change a domain.

Path

1. Introduction — what the three apps are.
2. System overview — processes and dependencies.
3. Backend architecture — where code lives.
4. Tenancy and Authentication.
5. Local development — boot the stack.
6. Pick one flow and trace it:
   • Create order
   • Inventory publish
   • Channel sync
7. Read Conventions before adding a module.

Rules that are enforced in this repository

These are project rules from AGENTS.md and docs/AI_CONTEXT.md, plus behavior the code implements. They are not a style guide copied from NestJS.

• Feature modules live under src/modules/<area>/<feature>/. Area modules only compose them. yarn architecture:check is the ratchet.
• Controllers do not inject DatabaseService.
• Provider SDKs stay under src/integrations. Feature modules do not import them.
• Cross-module stock writes go through StockOperationsPort.
• A new Prisma model must be classified in tenancy.extension.ts.
• Order side effects in order command go through OutboxWriterService.enqueue inside the transaction. Do not EventEmitter2.emit from that path.
• @RequirePermissions is opt-in. Omitting it allows any authenticated user, subject to the other guards.
• Queries on models with deletedAt are expected to filter deletedAt: null. The analysis did not prove every query does this.

What is still unknown

Read Open questions before you treat a comment in a state-machine file as the spec. The order map and its header comment disagree. The map is what runs.

Clients

Admin local URL expected by the API example env is http://localhost:5173 (ADMIN_APP_URL). The admin app reads VITE_API_URL (example http://localhost:3001).

The warehouse app reads EXPO_PUBLIC_API_URL. Its README says the client falls back to https://devapi.pointnxt.com when that variable is unset.