Architecture and data

This page is the inside view of the platform described on Architecture: what each application may do, how the shared packages depend on each other, which module owns which data, and the rules that keep that data consistent from the HTTP request to the database commit. Module responsibilities are on the service catalogue; the models themselves on the database design.

Application boundariesCopy Anchor Link

One API owns every rule and every byte of data (ADR-003); everything else is a client.

Shared packagesCopy Anchor Link

Dependency rulesCopy Anchor Link

1. Only apps/server depends on @hoco/db. The Next apps have no Prisma client and no DATABASE_URL (ADR-003).
2. @hoco/contracts is pure. Zod, @orpc/contract and @hoco/shared only — no server code, no Prisma types, no Node APIs — so it can be bundled into browsers and exported to OpenAPI without a running server.
3. @hoco/shared has no dependencies and no I/O; it is the only code that runs identically on the server, in browsers and in tests.
4. @hoco/ui knows nothing about the API. Data fetching lives in the apps.
5. Server-only secrets never reach a browser bundle. @hoco/env/dashboard and @hoco/env/web expose only NEXT_PUBLIC_* client variables; anything else read in a client component fails the build.
6. Inside the server, modules import each other only through modules/<name>/index.ts; repositories touch only their module's tables (service catalogue).

Enforcement: the dependencies declared in each package.json (pnpm's strict node_modules makes undeclared imports fail), plus a restricted-imports lint rule in biome.json forbidding @hoco/db and @prisma/* outside apps/server and packages/db, and cross-module imports other than index.ts inside the server. Enum values are defined once in @hoco/contracts; a server test asserts they equal the Prisma enums and apps/docs/content/spec/enums.json.

Data ownershipCopy Anchor Link

The system of record: every table has one owning module, the only one that writes it. "Written by" lists the operations and jobs that change the data — always through the owner's service; "Read by" lists the modules (in-process) and apps (through the API). Field-level details are on the database design pages linked in each heading's domain.

Identity and accessCopy Anchor Link

Geography and zonesCopy Anchor Link

CRMCopy Anchor Link

Catalog and pricingCopy Anchor Link

StockCopy Anchor Link

Orders and deliveryCopy Anchor Link

FinanceCopy Anchor Link

Promotions and loyaltyCopy Anchor Link

Field operations and invitationsCopy Anchor Link

Support and notificationsCopy Anchor Link

PlatformCopy Anchor Link

Consistency rulesCopy Anchor Link

TransactionsCopy Anchor Link

• One command, one transaction. A mutating procedure runs its whole effect inside withTx(ctx, fn) — a Prisma interactive transaction with maxWait 2 s and timeout 10 s, isolation READ COMMITTED. Cross-module invariants are service calls that receive the same tx.
• Nothing external inside. No HTTP call, no Redis publish, no queue add, no file upload inside fn; those happen after commit, through the outbox.
• Explicit row locks (SELECT … FOR UPDATE in the owner's repository) where two writers can race: the order being transitioned, the cart at checkout, CreditAccount, the promotion cap counter, StockLevel rows, NumberSequence. Locks are always taken in the same order to prevent deadlocks: cart → order or return → credit account → promotions → stock levels (sorted by variant id, then warehouse id) → number sequence.
• Retry of conflicts. A Prisma write conflict or deadlock (P2034) re-runs fn up to two times — safe because nothing external happened yet — then answers 500 INTERNAL_ERROR, which clients retry with the same Idempotency-Key.
• Database guards. statement_timeout of 15 s on the application role; idle_in_transaction_session_timeout of 15 s.

OutboxCopy Anchor Link

ctx.emit(tx, event) buffers events during the transaction; withTx inserts them as OutboxEvent rows just before commit, together with the AuditLog entries collected by ctx.audit(). A rolled-back command emits nothing. The worker dispatches committed events to handlers and to the SSE streams (outbox dispatcher).

IdempotencyCopy Anchor Link

Every mutating operation accepts Idempotency-Key; it is required on cart.checkout, sync.batch, every delegate.* mutation and every operation flagged in the API reference.

1. The idempotency step hashes the canonical request (operation id, path parameters, sorted JSON body) and looks up IdempotencyRecord by (caller, key). The caller is the user id, or the device id and IP for public operations such as invitations.attribute.
2. Completed, same hash → the stored status and body are replayed with Idempotent-Replayed: true; nothing runs.
3. Same key, different hash → 409 IDEMPOTENCY_KEY_REUSED.
4. In progress (lock not expired) → 409 IDEMPOTENCY_IN_PROGRESS; the client retries after a second.
5. New → a record with status: null (in progress), then the procedure runs; a record still in progress after 60 s is treated as abandoned and taken over by the next attempt.
6. Completion happens inside the business transaction: withTx writes the response snapshot to the record before commit, so a crash can never leave a change committed without its replay record.
7. What is stored: 2xx responses and business refusals (400, 403 OUT_OF_SCOPE, 404, 409 conflicts, 422) — a replay returns the same refusal, and a corrected action is a new action with a new key (sync.batch). Transient outcomes are not stored, so the same key can be retried: 5xx, 401, 429, 409 IDEMPOTENCY_IN_PROGRESS.
8. Records are kept 30 days (sync.purgeIdempotencyRecords).

Optimistic lockingCopy Anchor Link

Aggregates edited from several places carry an integer version (database design): Order, Tour, Visit, CreditAccount and Reseller (edited offline by delegates). Other aggregates rely on status guards in their UPDATE, and counters (stock levels, promotion caps, number sequences) on atomic increments. Responses include version; edits and transitions send it back; the repository updates with WHERE id = $1 AND version = $2 and increments it. Zero rows updated → 409 VERSION_CONFLICT with details.current (the current representation), and the client shows what changed. Offline edits from the delegate app carry the version they were made against; a mismatch comes back as a sync CONFLICT with the current record, and the app re-applies the delegate's own changes on top of it as a new action (offline sync design).

Integrity in the databaseCopy Anchor Link

The database is the last line of defence; services check first and give the friendly error.

Business numbersCopy Anchor Link

settings.nextNumber(tx, type) locks the NumberSequence row of (type, year), increments it and formats the number (CMD-2026-000158). Because the increment is part of the business transaction, a rollback gives the number back: invoice and credit-note numbers stay gapless, as invoicing requires.

SnapshotsCopy Anchor Link

Orders snapshot what the reseller agreed to at submission: product names, references, the selected price of the reseller's customer type, VAT rate, promotions, address. Invoices and credit notes snapshot their lines. A later price, name or address change never alters a past document.

Eventual-consistency budgetCopy Anchor Link

CachingCopy Anchor Link

Never cached: prices for a signed-in caller, availability, carts, orders, finance, anything personal. Correctness first; the database is fast enough at HOCO's scale.

HTTP cachingCopy Anchor Link

Server-side cachesCopy Anchor Link

Redis runs with noeviction (BullMQ needs it), so every cache key has a TTL and memory is alerted on at 70 %.

Query clientsCopy Anchor Link

The Next apps use TanStack Query through createApiQueryUtils(). Defaults (the scaffold sets staleTime: 30_000 in apps/dashboard/src/utils/orpc.ts):

new QueryClient({
	defaultOptions: {
		queries: {
			staleTime: 30_000, // lists and details
			gcTime: 5 * 60_000,
			refetchOnWindowFocus: true,
			retry: (failureCount, error) => isRetryable(error) && failureCount < 2, // never on 4xx
		},
		mutations: { retry: false }, // a retry re-sends the same Idempotency-Key explicitly
	},
});

Mobile caches are Imad's: the reseller app caches reference data, catalog pages and images for read-only browsing with an offline banner; the delegate app keeps its offline scopes in drift (mobile offline sync).

File flowsCopy Anchor Link

Every file is a File row plus an object in one of two buckets (ADR-009). Limits come from FilePurpose:

Upload (photos, documents, proofs, attachments):

Object keys are {purpose}/{yyyy}/{mm}/{fileId}.{ext}: no names, phones or other personal data in keys.

Request lifecycleCopy Anchor Link

Every request crosses the same chain. Steps 1–3 exist in the scaffold (apps/server/src/app.ts); the others land with SRV-04 to SRV-06.

Error handlingCopy Anchor Link

Every error leaves the API as an HTTP status and the envelope defined on the API reference: { "error": { "code", "message", "details", "requestId" } }. Codes are stable UPPER_SNAKE_CASE and registered on Errors; messages are localised from Accept-Language (French by default) through server catalogs keyed by code, with details values interpolated.

Client retry rule (all apps): retry only network failures, 408, 429 (after Retry-After), 409 IDEMPOTENCY_IN_PROGRESS (after a second) and 5xx, always with the same Idempotency-Key, with exponential backoff; never retry other 4xx. Logging rule: 4xx at info (bursts of 401/403 per IP at warn), 5xx at error with stack and Sentry.

ObservabilityCopy Anchor Link

Performance targets (NFR-01): server-side p95 under 300 ms for catalog reads and facets, under 800 ms for writes, under 1.5 s for checkout — verified by the load test of SRV-28 and detailed with the other cross-cutting targets on cross-cutting requirements.

ConfigurationCopy Anchor Link

Two kinds of configuration, never mixed:

• Environment variables — infrastructure, endpoints and secrets. One .env at the repository root locally (cp .env.example .env; found by @hoco/env/load from any folder); per-service variables in Dokploy elsewhere. Validated at boot by @hoco/env/server (t3-env + Zod): a missing or malformed value stops the process with a clear error.
• Business settings — Setting rows edited in the back-office (BO-64), validated, audited and cached 60 s: order minimum, reservation and deduction statuses, invoice trigger, GPS tolerance, sampling, retention, return window, assisted-order delay, payment methods, credit policy… Never an environment variable.

Variables marked planned are not in .env.example yet; each is added there and in @hoco/env/server (or the Next app's schema) by the task that introduces it.