---
url: /reference/ROADMAP.md
---
# Ninaku Backend Roadmap

Status: **working roadmap for `ninaku-app-api`**.

This roadmap defines the implementation order for the NestJS backend. The goal is to avoid building business features before the runtime, environments, module boundaries and database-access rules are stable.

The order matters. A later phase should not be started by bypassing unresolved foundations from an earlier phase.

***

## Phase 0 — Environments and delivery baseline

**Objective:** make the project reproducible, safe to run, testable and deployable before business modules are implemented.

### 0.1 Local environment

Establish a deterministic local developer setup.

Required outcomes:

* Node.js 24 pinned and verified.
* npm install/build/test commands reproducible.
* PostgreSQL 18 local runtime documented and scripted.
* `ninaku_migrator` and `ninaku_runtime` roles created correctly.
* canonical baseline installation automated.
* local database reset/rebuild process documented.
* environment-variable loading defined.
* no secrets committed to Git.
* one command or short documented sequence to boot the application locally.

The local environment must exercise the same security model expected in deployed environments: the application runs as `ninaku_runtime`, never as database owner/superuser.

### 0.2 Environment model

Define the supported environments and their purpose.

Initial target:

```text
local
  developer machine

test / ci
  disposable environment for automated verification

development
  shared integration environment

staging
  production-like validation environment

production
  customer traffic and real data
```

For each environment define:

* configuration source;
* database instance and credentials;
* migration policy;
* secrets management;
* log level;
* external provider mode/sandbox;
* storage configuration;
* domain/base URLs;
* CORS policy;
* telemetry destination;
* data retention expectations.

### 0.3 Configuration contract

Create a typed configuration layer.

Configuration must fail fast when a required value is absent or invalid.

Define at minimum:

* application environment;
* HTTP port/host;
* PostgreSQL connection settings;
* pool configuration;
* request/transaction timeout defaults;
* public API base/version settings;
* logging/telemetry settings;
* provider credentials only when the corresponding integration is enabled.

Do not scatter `process.env.*` access through business modules.

### 0.4 Database lifecycle

Formalize how the database moves between versions.

Required outcomes:

* clean install remains available for new databases;
* baseline manifest remains auditable;
* forward migrations have an explicit convention;
* migrations run with `ninaku_migrator`;
* application traffic uses `ninaku_runtime`;
* migration execution is separate from normal application startup unless explicitly decided otherwise;
* rollback/recovery strategy is documented per migration class;
* compatibility with rolling/staged application deployments is considered before destructive changes.

### 0.5 CI gates

The existing application and database workflows become mandatory quality gates.

Target checks:

* dependency install;
* lint;
* formatting check;
* TypeScript build/typecheck;
* unit tests;
* e2e tests;
* database static review;
* SQL sweep;
* clean-install regression suite;
* concurrency/contract tests;
* migration verification when migrations exist.

Future additions may include dependency/security scanning and architecture boundary checks.

### 0.6 Deployment baseline

Before production features are released, define:

* build artifact/container/runtime strategy;
* health/readiness endpoints;
* graceful shutdown;
* connection draining;
* database pool sizing;
* deployment command/process;
* rollback process;
* environment-specific migration step;
* log/trace correlation;
* minimum operational dashboard/alerts.

### Exit criteria for Phase 0

Phase 0 is complete when a new developer or CI runner can clone the repository, configure an environment, install the canonical database, run the application/tests, and understand how the same application is promoted toward staging/production without using privileged database credentials at runtime.

***

## Phase 1 — Define the module map before implementing modules

**Objective:** decide ownership, boundaries and contracts before generating controllers/services/entities.

This phase is design work backed by the current canonical SQL and real product flows.

### 1.1 Inventory the domains

Start from the current canonical schemas/modules and classify each one as:

* Platform Core;
* shared business capability;
* cross-cutting capability;
* vertical-specific capability;
* installation/technical artifact.

Initial module candidates include:

```text
reference
organization
party
identity
platform
assets
catalog
pricing
commerce
sales
settlement
payments
operations
kitchen
fulfillment
inventory
production
procurement
crm
loyalty
receivables
payables
cash
treasury
tax
fiscal
invoicing
accounting
workforce
documents
printing
notifications
communications
integrations
events
sync
audit
analytics
```

This list is not permission to create one Nest module blindly for every SQL file. Each boundary must be validated against real ownership and workflows.

### 1.2 Module definition template

Before implementing a module, document:

1. **Business responsibility** — what problem it solves.
2. **Owned facts** — what data/state only this module may mutate.
3. **Tables/schemas used** — and why each one exists.
4. **Inbound use cases** — real actions another actor/module needs.
5. **Outbound dependencies** — contracts it consumes from other modules.
6. **Public in-process contracts** — what other modules are allowed to call.
7. **HTTP API surface** — business-oriented endpoints, if any.
8. **Authorization/scopes** — who may perform each action.
9. **Tenant/RLS context** — required organization/BU/legal entity/outlet scope.
10. **Transactional invariants** — what must commit atomically.
11. **Concurrency/idempotency rules** — where duplicates/races matter.
12. **Offline behavior** — if the capability must accept replayed commands.
13. **Events produced/consumed** — only where there is a real integration need.
14. **Performance/query patterns** — expected hot reads/writes and indexes to validate.

A module is not ready for implementation while these answers are materially unclear.

### 1.3 Table-to-capability traceability

For each canonical table touched by an implemented capability, establish:

* owner;
* purpose;
* writer;
* readers/consumers;
* lifecycle;
* key invariants;
* retention/audit behavior;
* expected indexes/query patterns.

Tables with no defensible purpose should be reviewed instead of automatically exposed through CRUD.

The target is not to force every table into a public API. Some tables legitimately exist for ledgers, outbox/inbox, audit evidence, snapshots, projections, provider mappings, historical assignments or technical coordination.

### 1.4 Optimize before adding structures

When a feature appears to require a new table/module/API:

1. inspect the existing model;
2. determine whether the existing aggregate/table can represent the fact correctly;
3. verify ownership and lifecycle;
4. inspect constraints/indexes and query patterns;
5. only then propose a new structure.

If the current schema is redundant, overly coupled or mixes ownership, optimize it through an explicit reviewed migration rather than preserving bad structure simply because it already exists.

### 1.5 Suggested boundary-definition order

Define modules in dependency/order-of-foundation sequence:

```text
1. reference
2. organization
3. platform
4. party
5. identity
6. events / audit / sync contracts
7. catalog
8. pricing
9. sales
10. settlement
11. payments
12. cash / treasury
13. inventory
14. procurement
15. tax / fiscal / invoicing
16. accounting
17. restaurant-specific modules
18. retail-specific modules
19. hospitality-specific modules
20. optional CRM / loyalty / workforce / analytics capabilities
```

This ordering is not immutable. It exists to avoid implementing a downstream capability before its ownership/context model is understood.

### Exit criteria for Phase 1

Phase 1 is complete enough to start implementation when the first module slice has a clear owner, real use cases, contracts, table traceability and dependency direction, and the broader module map has no obvious ownership collisions.

***

## Phase 2 — Application foundation

**Objective:** implement reusable technical mechanisms before business-heavy modules.

Recommended order:

1. typed configuration;
2. runtime PostgreSQL adapter/connection pool;
3. request context;
4. tenant/RLS context propagation;
5. transaction manager / unit-of-work boundary;
6. API error/problem contract;
7. validation conventions;
8. idempotency infrastructure;
9. events/outbox foundation;
10. observability/logging/trace correlation;
11. module public-contract conventions;
12. architecture tests/lint rules where practical.

This phase must not become a generic framework project. Build only mechanisms required by real upcoming use cases.

### Delivery slices and current scope

Issue #13 tracks four main slices, **not exactly four pull requests**. The current normative HTTP/observability specification and acceptance matrix live in [FOUNDATION\_HTTP\_AND\_OBSERVABILITY.md](../contracts/FOUNDATION_HTTP_AND_OBSERVABILITY.md). Publishing that specification does not complete its implementation.

| Slice | Purpose | Required outcome |
| --- | --- | --- |
| A | Typed configuration, safe runtime pool and health endpoints | Safe startup and verifiable PostgreSQL connectivity; delivered by PR #14/#16 |
| B | Request context, authorized tenant context, use-case transactions and RLS | No cross-request/tenant context leakage; atomicity and isolation proven against PostgreSQL |
| C | HTTP contract and observability | Reusable request/response, cursor, validation, error, logging/tracing and OpenAPI mechanisms |
| D | Operational and performance validation | Reproducible staging evidence, thresholds and instrumentation-cost measurements |

C is delivered incrementally:

| Delivery | Scope |
| --- | --- |
| C1 | Natural request payloads; `data` and optional `meta`; types, status codes, headers and protocol exceptions |
| C2 | `meta.pageInfo`; opaque/versioned/protected cursors; bounded limits, filters, sorting and explicit consistency |
| C3 | Body/path/query/header validation with the selected Zod/Standard Schema mechanism |
| C4 | RFC 9457 Problem Details, stable codes, one validation-error list schema and safe failure mapping |
| C5 | Nest JSON logger behind a small Ninaku boundary; OpenTelemetry/W3C tracing; metrics; data minimization; bounded export and audit separation |
| C6 | OpenAPI generation/validation, examples, runtime-contract checks and compatibility/security tests |

Each implementation PR includes tests and follows work branch → staging → main. C2 does not own every module's SQL or invent a universal query engine. C5 does not implement the audit behavior of future business modules. Idempotency headers and event conventions do not replace durable idempotency/outbox implementation and its own tests.

D measures the available A/B/C paths, including latency, errors, pool pressure, memory and telemetry volume/overhead. A health-check load test is not proof of Sales/Payments capacity; add representative business flows when those modules exist.

### Exit criteria for the Foundation delivery

Before marking issue #13 complete, require implemented slices and linked evidence, not only documentation or a green build:

* the HTTP success/error contracts, exceptions and data representations are consistent;
* cursor validation and authorization reject incompatible/cross-tenant use;
* concurrent requests do not mix tenant/request/trace context;
* test secrets are absent from public errors, logs, traces and exported output;
* a staging request ID locates its logs and instrumented execution;
* telemetry-destination failure and shutdown remain bounded and observable;
* OpenAPI agrees with implemented responses and incompatible changes are detected;
* D records its exact commit, environment, dataset, load, thresholds and limitations.

Cursor protection/expiry (C2) and the telemetry destination (C5, Grafana Cloud) are resolved; see [DECISIONS.md](DECISIONS.md) and [FOUNDATION\_HTTP\_AND\_OBSERVABILITY.md](../contracts/FOUNDATION_HTTP_AND_OBSERVABILITY.md). What remains open before closing C5 is the sampling policy — `AlwaysOnSampler` today, no sampling — and the retention, access and volume/cost budget decision for logs and traces per environment. Do not leave these transverse decisions to each business module. Production provisioning/recovery remains a separate gate in issue #7; no production activation is implied here.

***

## Phase 3 — Organization and platform topology

**Objective:** make Ninaku able to represent and authorize a real customer/business structure.

Implement use cases around:

* organization creation/onboarding;
* Business Units;
* Legal Entities;
* Brands;
* Sites;
* Outlets;
* vertical/capability activation;
* effective assignments and historical validity;
* tenant context resolution.

This phase should prove the RLS/runtime-role path with real application requests.

***

## Phase 4 — Identity, authentication and authorization

**Objective:** authenticate principals and resolve effective access to Ninaku scopes.

Cover:

* principal/user lifecycle;
* login/session/token strategy;
* memberships;
* roles/permissions/capabilities;
* scope resolution;
* organization/BU/legal entity/site/outlet access;
* suspension/recovery rules;
* security audit evidence.

Authentication is not considered done if it merely returns a token. It must integrate with the existing tenant/RLS model.

***

## Phase 5 — Onboarding and session context

**Objective:** provide a coherent entry path for frontend applications.

Possible outputs:

* onboarding workflow;
* business selection/context;
* enabled capabilities;
* effective permissions;
* outlet/legal entity defaults;
* localization/currency/timezone context.

Avoid making the frontend discover the domain by calling dozens of CRUD endpoints.

***

## Phase 6 — Shared commercial core

Implement shared capabilities in slices, based on real workflows rather than complete-table CRUD.

Suggested sequence:

```text
Catalog
Pricing
Sales
Settlement
Payments
Cash
Inventory
Procurement
```

For each slice:

* define the workflow;
* trace tables;
* expose task-oriented APIs;
* enforce ownership;
* cover authorization/RLS;
* add concurrency/idempotency where relevant;
* add integration/e2e tests;
* measure critical SQL/query paths.

***

## Phase 7 — Fiscal and financial capabilities

Progressively implement:

```text
Tax
Fiscal
Invoicing
Receivables
Payables
Treasury
Accounting
```

Do not make advanced accounting/fiscal modules mandatory dependencies for a minimal operational profile unless the actual business/regulatory flow requires them.

***

## Phase 8 — Restaurant vertical

Compose shared modules with genuinely restaurant-specific capabilities.

Potential slices:

* service areas/tables;
* restaurant reservations;
* service sessions;
* kitchen routing/work;
* fulfillment/delivery/pickup bridges;
* printing integration;
* production/recipe integrations where enabled.

The restaurant vertical should not duplicate Catalog, Sales, Payments or Inventory.

***

## Phase 9 — Retail vertical

Build retail-specific workflows over the shared platform without kitchen/service-table dependencies.

Validate that a minimal retail profile can operate without installing restaurant-specific behavior.

***

## Phase 10 — Hospitality vertical

Add hotel/property capabilities with their own ownership boundaries.

Potential modules/slices:

* property/accommodation structure;
* room types/units;
* availability/inventory of accommodation;
* reservations;
* stays/check-in/check-out;
* folios;
* housekeeping;
* OTA/channel-manager integrations.

Hospitality consumes shared Party, Pricing, Payments, Documents, Notifications, Accounting and other relevant capabilities, but does not reuse restaurant reservation aggregates as hotel reservations.

***

## Phase 11 — Advanced and optional capabilities

Implement only when product demand justifies them:

* CRM;
* loyalty;
* workforce/payroll;
* advanced analytics/projections;
* communications;
* broader integrations;
* additional verticals.

***

## Delivery rule for every phase

Every implementation PR should answer:

* What real business problem/use case is being delivered?
* Which module owns it?
* Which tables are used and why?
* Are new tables/columns truly required?
* Which APIs are exposed and why do they represent business tasks rather than tables?
* What are the authorization/RLS rules?
* What are the transaction and concurrency guarantees?
* Is idempotency required?
* What happens offline/retry-wise?
* What tests prove the behavior?
* What operational/observability impact does it have?

A phase is not complete because files/controllers/entities exist. It is complete when a coherent business capability works end-to-end under the architectural and database contracts.