Skip to content

System Flows ​

Each flow in one diagram, a few plain lines and the routes it uses. Built from docs/generated/openapi.json, the controllers, database/canonical and the e2e specs named in each section. Where this page and OpenAPI differ, OpenAPI wins for a route shape and the code wins for behavior. What is not verified says so.

Every route is under /api/v1, needs Authorization: Bearer <accessToken> and, for tenant routes, X-Organization-Id. Public routes are marked. Shared conventions and error codes: CLIENT_INTEGRATION.md.

1. Sign-up, sign-in, session ​

The first call of every session is GET /session/context. It says who the caller is, whether they belong to an organization, and, with X-Organization-Id, their roles, permissions, plan capabilities, profile and workspace.

A renewal spends the refresh token; presenting a spent one ends the session.

RouteAccess
POST /sign-ups, POST /sign-ups/confirmationspublic
POST /provider-nonces (Google, Apple)public
POST /sign-ins, POST /sign-ins/second-factors, POST /sign-ins/renewalspublic
GET /session/contextsession
POST /sign-outs, POST /sign-outs/everywheresession

Proof: session-context*.e2e-spec.ts, session-renewal.e2e-spec.ts, IDENTITY_CASE_MATRIX.md.

2. Organization and guided onboarding ​

POST /organizations makes the caller owner. POST /organization/onboarding creates the first legal entity, brand, site and outlet in one transaction and the default sales channel; it only works on an empty organization. Setup steps it does not do: stock location and catalog assignment. Both need Idempotency-Key.

RoutePermission
GET /reference/metadata, GET /planssession, public
POST /organizationssession, no organization header
POST /organization/onboardingorganization.structure.manage
GET /organization/setuporganization.structure.view

Errors: 409 organization.first_run_conflict, 409 organization.plan_limit_reached, 422 organization.structure_refused. Proof: onboarding.e2e-spec.ts, reference-metadata.e2e-spec.ts.

3. Organization structure ​

Business unit and legal entity are dated assignments of an outlet, not columns. Outlet groups may overlap, never twice for the same outlet at once. A stock location belongs to a legal entity and sits at the organization, a business unit or an outlet. Plans cap active sites, business units and outlets (409 organization.plan_limit_reached).

Scoped admin: organization.structure.view and .manage work at a scope. A viewer scoped to a business unit sees its outlets and their site and brand, nothing else. A scoped manager may rename inside the scope; creating a site, brand or business unit needs organization-wide rights; a site or brand scope may open outlets. Outside the scope the answer is the same 403 as for an unknown id.

RoutePermission
GET /organization/structure, GET /outlet-groups, GET /schedules, GET /sales-channelsorganization.structure.view
POST/PATCH /outlet-groups, PUT /outlet-groups/{id}/membersorganization.structure.manage
POST /schedules, PUT /schedules/{id}/windows, GET .../occurrencesorganization.structure.manage (read: view)
POST/PATCH /sales-channelsorganization.structure.manage
PUT /legal-entities/{id}/tax-identifiers (configuration only)organization.structure.manage
POST/PATCH /locations, .../deactivation, .../reactivationinventory.locations.manage
GET /locationsinventory.locations.view
PUT /outlets/{id}/issue-location-rulesinventory.locations.manage at the outlet
PATCH and deactivate or reactivate of sites, outlets (and POST /outlets)organization.account.manage or organization.structure.manage, the latter also scoped to the place
POST of sites, brands, business units, legal entitiesorganization.account.manage, organization-wide

Proof: structure-scoped-reads, structure-scoped-writes, structure-plan-limits, outlet-groups*, locations-*, issue-location-rules, schedules, sales-channels, legal-entity-tax-identifiers (test/e2e/*.e2e-spec.ts).

4. Roles, permissions, scopes, invitations ​

A role is held at a scope: organization, business unit, legal entity, brand, site, outlet or outlet group. Critical rule: a role that grants organization.account.manage is never offered by invitation or role assignment. The only way to make another administrator is the ownership grant, by an organization-wide administrator, with a live step-up (x-elevation-token), a reason and Idempotency-Key.

Admin permissions: organization.account.manage is the superset of organization.structure.view/manage and identity.team.manage. The code accepts identity.team.manage in place of the administrator permission on invitations, the member list, member control and role assignments (can-manage-organization.ts); the OpenAPI text still names only organization.account.manage. Whether a scoped (not organization-wide) holder passes: not verified.

RoutePermission
GET /permissions, GET/POST /roles, PUT /roles/{id}, GET /offerable-rolesorganization.account.manage
POST /invitations, .../reissue, .../revocation, GET /invitations, GET /membershipsorganization.account.manage or identity.team.manage
POST /memberships/{id}/role-assignments, PATCH/DELETE /role-assignments/{id}same
POST /step-ups, POST /step-ups/confirmationssession
POST /memberships/{id}/ownership-grantsorganization-wide administrator + elevation

Errors: 403 identity.role_assignment_privilege_exceeded, 403 identity.invitation_privilege_exceeded, 403 identity.elevation_required, 422 identity.ownership_grant_refused. Proof: ACCESS_CASE_MATRIX.md, scoped-admin, ownership-grants* e2e specs.

5. Approvals by PIN ​

A rule says "this permission needs another member's approval", for the whole organization or for one business unit, outlet or outlet group. A threshold (amount, percent or units) asks for approval only above the value. The approver types their own PIN; the approval is bound to the requester, the action key and an optional payload hash, expires, and is spent once. Five wrong PINs per pair lock it for 15 minutes. Built: settings, PIN, grant, can-approve. Not built: no business route consumes an approval yet; identity.require_approval is only called in SQL.

RoutePermission
GET/PUT /approvals/settingsorganization.account.manage
PUT /memberships/{own id}/pinthe caller
POST /approvalssession; 409 identity.approval_not_required, 403 identity.approval_denied
GET /approvals/can-approvesession

Proof: approvals, approval-settings*, member-pin e2e specs.

6. Settings and the business day ​

The most specific override wins: outlet, then outlet group, then business unit, then organization, then the default. A lock set on a business unit or outlet group freezes the scopes below it (409 settings.locked_by_parent). Every answer says where the value came from (origin). Writes need If-Match with the ETag of the list.

Three settings exist: inventory.negative_stock_mode (prevent, allow), operations.business_day.cutoff_minutes (0 to 1439, default 0) and inventory.default_receiving_location.

At 01:30 with a 02:00 cutoff, the order belongs to the previous business day. A sale uses the currency of the outlet.

RoutePermission
GET /settingssettings.assignments.view (+ ETag, 304)
PUT/DELETE /settings/{code}/assignmentsettings.assignments.manage
PATCH /organization (default currency, locale), POST/PATCH /sites (country, time zone, currency, locale)organization.account.manage

Scope organization or business_unit or outlet_group needs the permission organization-wide; outlet needs it at that outlet. Errors: 403 settings.action_forbidden, 404 settings.scope_not_found, 422 settings.value_invalid. Proof: settings-*, sites-regional, sales-regional-profile e2e specs.

7. Catalog to price, quota, supply and sale ​

The client sends variants, quantities, options, combo choices, channelId, serviceMode, menuId and quota overrides; never a price or a currency. The server prices the cart once (outlet book, then channel, menu and service mode, the rule in force and its schedule), draws the quota pools and stores the serviceMode on the order, unchangeable after the sale. A variant with no price is refused with 422 sales.price_unresolvable; an explicit price of 0 sells at zero. An exhausted blocking pool is 409 sales.capacity_exceeded; a warning pool lets the sale through with a warnings entry; an override needs an approval of operations.quotas.override. Not enough stock aborts the whole sale. The same key and request replays the order with 200; the same key with another serviceMode is 409 idempotency.key_reused.

RoutePermission
Catalog admin (items, variants, menus)catalog.*, see CATALOG_USE_CASES.md
GET/PUT/PATCH /price-list, /pricing/*pricing.prices.view / manage (POST /pricing/resolve also sales.orders.take at the outlet)
/operations/poolsoperations.quotas.view / manage
/outlets/{id}/availabilityoperations.availability.view at the outlet
/catalog/outlets/{id}/blocksoperations.availability.block at the outlet
/inventory/supply-routesinventory.supply_routes.view / manage
POST /outlets/{id}/salessales.orders.take at the outlet
GET /outlets/{id}/sales/{orderId}sales.orders.read
StatusCode
400foundation.validation_failed (no key, unknown field, a price)
403sales.action_forbidden (also unknown or foreign outlet), sales.approval_required, sales.approval_invalid
409sales.insufficient_stock, sales.capacity_exceeded, sales.currency_mismatch, idempotency.key_reused
422sales.lines_not_sellable, sales.price_unresolvable, sales.order_refused

Detail: SALES_USE_CASES.md.

8. Price edit ​

PATCH is a delta (up to 500 changes): variants not named keep their price, an equal price changes nothing, a different one closes the old entry as history. Another schedule for a variant that has one is 409 pricing.price_schedule_conflict. PUT still replaces the whole list. One list per currency, tax exclusive. Needs pricing.prices.manage (owner, manager); reads need pricing.prices.view. Proof: price-list-edit, price-list-reads e2e specs; PRICING_USE_CASES.md.

9. Stock today ​

In SQL: supply routes, reservations, the ledger, goods receiving and the negative-stock mode. Through REST, stock only moves inside a sale, and locations, issue rules and supply routes are administered (flows 3 and 7). No REST route exists for receiving, balances or counts.

10. Audit read ​

GET /audit-events (audit.events.view, held by the owner role by default): newest first, keyset cursor, filters resourceKind, actorIdentityId, outletId, from, to. It never returns network addresses or the changed values. A holder at one outlet must name that outlet. Proof: audit-events.e2e-spec.ts.

11. Not built yet ​

  • Payments, till and cash shifts, credit and receivables.
  • Promotions and discounts.
  • Receiving and purchase orders over REST (built on unmerged branches).
  • E-invoicing and country tax: an external service; this API only holds configuration (legal entity tax identifiers). A sale carries no tax.

Roadmap: R1 (the foundation above: reference data, settings, audit read, locations, onboarding, structure, approvals, plan limits, price edit) is merged. The R2 to R6 plan is kept outside this repository, so its content is not verified here. The phase order is in ROADMAP.md.

Application Foundation in progress. Tracked in issue #13.