Skip to content

Ninaku CoreThe backend, documented as it actually runs

A modular monolith on NestJS and PostgreSQL. Every contract here is enforced by executable checks run before every merge, and the API reference is generated from the running service — not written by hand.

NinakuNinaku

Start here ​

If you areStart withThen read
New to the codebaseArchitectureDomain map
Building or changing an endpointFoundation HTTP contractAPI and schema discipline
Understanding how the system flowsSystem flowsClient integration
Integrating against the APIClient integrationAPI reference
Looking for a past decisionDecisionsRoadmap

What exists today ​

The service exposes 292 operations on 238 paths, counted from docs/generated/openapi.json (the client integration guide shows the count per group and the command that recounts it):

  • Identity and access: sign-up, sign-in and sessions, sign-in methods, second factors, password, step-up, invitations, memberships, roles and the permission catalog, role assignments, ownership grants, approvals by PIN.
  • Organization: profile, guided onboarding, sites, brands, legal entities (tax identifiers as configuration), business units, outlets, outlet groups, schedules, sales channels, reference data and plan limits.
  • Settings, audit and stock locations: scoped settings with lock-below, the audit trail read, warehouses and issue rules.
  • Platform: plans, subscription and the staff administration of both.
  • Assets: uploads and the file library.
  • Catalog: items, variants, modifiers, menus, combos, categories, several catalogs, translations, allergens and nutrition, attributes, imports and exports, change sets, history and restore, and the outlet reads for the till and for offline devices.
  • Pricing: the price list per currency, delta edits, scheduled prices and history.
  • Sales: take and read an order at an outlet.

The two health probes stay unversioned and unprefixed on purpose, because Railway's healthcheck depends on that exact path; they are outside the data envelope. Every other route is under /api/v1/.

Not built yet: payments, till and cash, credit, promotions, price dimensions, quotas and availability, supply-route administration and receiving over REST. Receiving with serials, supply routes and the stock ledger exist in the database without a REST route. E-invoicing and country tax calculation belong to an external service. Each flow with a diagram: System flows; details: Client integration.

How this documentation stays honest ​

  • docs/generated/openapi.json is produced by npm run openapi:generate from the running application and its Zod schemas, then verified byte for byte by npm run openapi:check. It is never edited by hand.
  • The API reference renders that exact file, so it cannot drift from the service.
  • When documents disagree, authority runs in this order: automated contracts and the database manifest, then current architecture, then domain decisions, then historical evidence.
  • A change that touches architecture, schema, deployment or modules updates its owning document in the same pull request.

Application Foundation in progress. Tracked in issue #13.