Service catalogue

@hoco/server is a modular monolith (ADR-004): one codebase, two processes (api and worker), 24 modules with hard boundaries. This page is the reference for those boundaries — what each module owns, exposes, emits and consumes. It is the input of SRV-01 (freeze of the service catalogue), which precedes the database schema (SRV-02) and the API contract (SRV-03).

The data each module owns is detailed in the database design; the cross-module rules (transactions, idempotency, caching, request lifecycle) are on Architecture and data; queues and schedules on Jobs and scheduler.

Design principlesCopy Anchor Link

A module is a folder. apps/server/src/modules/<name>/ with the same files everywhere, implementing its key of the contract (packages/contracts/src/routers/<name>.ts) and registered in apps/server/src/router.ts. The scaffold's modules/README.md prefixes the files with the module name (orders.router.ts, orders.service.ts, orders.test.ts); either spelling is fine as long as all 24 modules use the same one — the roles are:

Rules every module follows.

1. Ownership. Each table has exactly one owning module (system of record). Only the owner writes it; other modules call the owner's service. The one read exception is analytics, which reads reporting views defined in migrations.
2. Routers compose, services form a graph without cycles. A router may orchestrate several modules (the catalog listing combines catalog search, price selection and availability). A service calls only services below it in the dependency graph; when two modules need each other, the caller passes data in instead of the callee reading it back.
3. Invariants are synchronous, reactions are events. Whatever must be true when the request returns (stock reserved at confirmation, credit checked, invoice number allocated, return restocked) runs in the same database transaction through service calls passing tx. Whatever can happen a second later (notifications, live streams, CRM lifecycle automation, analytics, sync hints) is a handler of an event written to the outbox in that transaction (ADR-007).
4. Contract first. A route exists in packages/contracts before it exists in a router; routers never add fields the contract does not declare (API reference).
5. Permission and scope in one place. policies.ts declares the permission key of each operation (orders.validate) and its scope (self, delegate, staff or public); the request pipeline enforces both before the handler runs, and repositories apply the scope as a query filter (request lifecycle).
6. One event per fact. Events are named <aggregate>.<past_fact> in lower snake case (order.validated, assisted_order.awaiting_confirmation), are emitted by the module owning the aggregate, carry ids and a minimal snapshot (no personal data beyond ids and business numbers), and are versioned (v: 1). A command may emit several events when it establishes several facts.
7. Handlers are idempotent and tolerate reordering. Delivery is at least once; a handler re-reads current state or compares versions instead of trusting arrival order (jobs and scheduler).

A service function, as every module writes it:

// modules/orders/service.ts (shape, not final code)
export async function validateOrder(ctx: Ctx, input: ValidateOrderInput) {
	return withTx(ctx, async (tx) => {
		const order = await repo.lockForUpdate(tx, input.orderId, ctx.scope);
		policies.assertTransition(order, "VALIDATED", ctx.actor); // 409 ORDER_TRANSITION_NOT_ALLOWED
		await inventory.reserve(tx, order.lines, { override: input.stockOverride }); // 422 STOCK_INSUFFICIENT
		await billing.assertCredit(tx, order, { override: input.creditOverride });
		const updated = await repo.transition(tx, order, "VALIDATED", ctx.actor, input.version); // 409 VERSION_CONFLICT
		ctx.audit(tx, { action: "VALIDATE", entity: updated });
		ctx.emit(tx, { key: "order.validated", aggregate: updated, payload: { orderId: updated.id } });
		return toDto(updated);
	});
}

Module mapCopy Anchor Link

DependenciesCopy Anchor Link

Service calls (an arrow means "calls the service of", inside the caller's transaction when needed). Platform modules — settings, audit, files, jobs, integrations — are used by every module and are not drawn. Dotted arrows are not service calls: sync invokes other modules' procedures, analytics reads reporting views.

Main event flows (emitter → consumers). Every event that has a rule in the notifications matrix or an SSE projection also flows to notifications.

ModulesCopy Anchor Link

identityCopy Anchor Link

Accounts and authentication for every population: staff, delegates and resellers. Configures Better Auth (ADR-005): phone or e-mail + password, OTP send and verify, bearer sessions for mobile and cookies for the web, session listing and revocation, lockout and OTP limits. It runs reseller sign-up — including the declared customer type and the claim of a prospect created in the field — password reset and change, devices (FCM tokens, app version, platform), account-status gating, staff and delegate user administration, and the guest path: optional-auth operations run without a session.

Sign-up composes three modules in one transaction: identity creates the user, crm claims or creates the reseller with its declared customerType (AUTH-11), invitations records the attribution.

Risks:

• SMS deliverability in Algeria gates sign-up and reset; the provider must be tested with the three mobile operators before the pilot.
• Duplicate accounts when a field prospect and a self sign-up share a phone: claim matching on the normalised E.164 phone (normalizeDzPhone) and a unique index.
• Lockout abuse (an attacker locking a reseller's phone): the lockout key is phone + IP, not phone alone.

accessCopy Anchor Link

Roles and permissions (module × action) with the editable matrix and its guard rails (a super admin cannot remove roles.administer from the last super admin). It provides the permission guard every procedure passes through, and the scope resolvers repositories use as query filters: self (the caller's reseller) and delegate (the delegate's zones and assigned resellers). It also holds field-level restrictions: purchase price, margins and credit visible only with the matching permissions (ACL-04).

Risks:

• A repository query that forgets the scope leaks data. repo.ts functions take a typed Scope argument, and the permission sweep of SRV-28 calls every operation with every role.
• Cached permissions go stale after a matrix change: 60 s TTL plus invalidation on role.permissions_changed.

geoCopy Anchor Link

The official wilaya and commune reference (FR/AR names, commune centroids) seeded from a versioned file, zones grouping communes, delegate coverage, distance helpers (haversine) and the nearest-commune lookup that turns a device position into a wilaya — used for regional WhatsApp support when the visitor is not signed in (SUP-05). Optional geocoding through the maps provider (GEO-04).

Risks:

• Changes to the official reference (new wilayas or communes) need a versioned seed and an ETag change.
• A commune in two zones makes delegate scope ambiguous. V1 rule: a commune belongs to at most one zone (unique ZoneArea.communeId) unless HOCO decides otherwise.

crmCopy Anchor Link

The commercial record of every point of sale: reseller and prospect data (minimum data set of cahier §15.5), the unique normalised main phone, the customer type (SUPER_GROS, DEMI_GROS, DETAIL) declared at sign-up and changed only by the back-office, the 10-status lifecycle with automatic transitions driven by events, assignment to a delegate and a zone with history, segments, the interaction timeline, follow-up tasks, documents and photos, the validation queue, and the reseller's self-service profile and delivery addresses.

Lifecycle automation only moves a reseller forward in the funnel and never lifts SUSPENDED (lifecycles); handlers recompute the status from facts (has an account, a first order, a delivered order) rather than from the event alone, so a late or duplicated event cannot regress it.

Risks:

• Duplicates across four creation paths, one of them offline: a unique index on the normalised phone, a check on every path, and the PHONE_ALREADY_EXISTS conflict on replay (offline sync).
• Reassignment history (ResellerAssignment.fromDelegateId) is also what tells a delegate's device that a point of sale left its scope (delta feed).
• Changing a customer type re-prices open carts on their next read and never touches submitted orders (prices are snapshotted).
• Assignment history drives reports and offline scope; it must be written on every reassignment, including bulk ones.

catalogCopy Anchor Link

Brands, the category tree (categories and sub-categories), products and variants (SKU, barcode, quantity limits, and the three selling prices priceSuperGros, priceDemiGros, priceDetail plus vatRate, recommendedPrice and the restricted purchasePrice), images, specs, per-category filterable attributes and their values per variant, product lifecycle including the automatic OUT_OF_STOCK, visibility rules, favorites, and the reseller home aggregate. Search, combinable filters and facets with counts serve guests and signed-in callers alike; for guests every price is null and the price-range facet is absent (AUTH-10, CAT-12, CAT-13).

The listing router composes three modules: catalog searches and filters, pricing selects the caller's price for each variant (none for guests), inventory adds the availability (IN_STOCK or OUT_OF_STOCK — never a quantity, STK-07). Saving a variant's prices calls pricing.recordPriceChange() in the same transaction.

Risks:

• Results under 3 seconds on a mobile connection (CAT-07) with facets computed on every query: one filtered base query, facet counts with GROUP BY on indexed attribute values, a p95 budget of 300 ms server-side measured in the load test of SRV-28.
• Guest responses must never leak a price or a quantity: one DTO mapper per audience, covered by contract tests.
• Attribute definitions change after products are filled: values are typed (number with unit, enum, boolean, text) and a definition in use can be deactivated, never deleted.

pricingCopy Anchor Link

V1 pricing is deliberately simple (PRC-01, PRC-02): each variant carries three selling prices, HT, one per customer type, and the reseller's customerType selects one; promotions then apply on top (cart engine); guests get no price. The module owns the selection function, VAT handling (basis points, 19 % by default per product), HT/TTC computation through the shared rounding helper, and the history of the three prices. Per-reseller agreements are V2 (PRC-03); quantity tiers are dropped.

selectPrice is a pure function: callers pass the variant's prices, so pricing depends on no other module.

Risks:

• HT/TTC rounding must be identical in catalog, cart, invoice and credit note — one helper in @hoco/shared, tested on real price lists.
• A price change between the cart view and checkout: checkout re-evaluates and answers 409 CART_CHANGED with the new totals (lifecycles).

inventoryCopy Anchor Link

Warehouses and stock levels per variant × warehouse (physical, reserved, available = physical − reserved), reservations and deductions triggered by the configured order statuses (default: reserve at VALIDATED, the back-office confirmation; deduct at SHIPPED), automatic restock — reservation release on cancellation or refusal, re-entry of deducted quantities when an order is cancelled after deduction, RETURN movements at return reception — the movement ledger, thresholds and alerts, inventory sessions, and the availability function used by catalog and cart. Quantities are back-office only; everyone else sees IN_STOCK or OUT_OF_STOCK.

Risks:

• Overselling under concurrency: a reservation is a conditional UPDATE … SET reserved = reserved + q WHERE physical - reserved >= q on the StockLevel row, plus the ledger insert in the same transaction; a recorded override is the only way past it (STK-08).
• Level and ledger drift: the nightly aggregates job also checks that levels equal the sum of movements and reports any difference.
• Which warehouse to reserve from when HOCO has several: V1 uses one default warehouse per wilaya (setting) unless the cadrage decides otherwise.

promotionsCopy Anchor Link

Promotions (PERCENT_OFF, AMOUNT_OFF, FIXED_PRICE, FREE_DELIVERY) on products, categories or brands, audience targeting (wilaya, segment, customer type, volume; level once V2 loyalty exists), schedule, stock cap, stacking rules and priorities, daily offers and banners, and the preview simulation. The application function is pure: the cart passes lines and reseller facts in, promotions returns the applied discounts.

Risks:

• Stacking ambiguities: the rules are fixed in business rules and tested with the preview endpoint.
• Cap races at checkout: the cap counter row is locked in the checkout transaction.
• Time boundaries: the cart engine evaluates startsAt/endsAt itself, so a late schedule job only delays the displayed status, never the price.

cartCopy Anchor Link

The server-side cart per reseller, shared by the app and the web (ORD-01), and the basket evaluator reused by checkout, assisted orders, back-office orders and order modifications: visibility and orderability of each line, price selection, promotions, availability, quantity rules, minimum amount, maximum per order, credit availability, delivery fee. cart.checkout (idempotent) hands the evaluated basket to orders. Guests cannot have a cart.

Risks:

• Double submission: required Idempotency-Key, plus a row lock on the cart during checkout.
• Totals changing between display and submission: checkout compares the totals the reseller saw and answers 409 CART_CHANGED with the re-evaluated cart.
• Evaluation cost: lines are evaluated in batched queries (one per module), never per line.

ordersCopy Anchor Link

The 11-status lifecycle with its transition table and actors (lifecycles). No order is ever confirmed automatically: every order — app, web, assisted, phone — lands as SUBMITTED (or PENDING when on hold) in the back-office « commandes à confirmer » queue and waits for admin.orders.validate (ORD-14). The module also covers controlled modification, refusal and cancellation (with automatic restock), assisted orders (draft → awaiting the reseller's confirmation → confirmed or rejected or expired after 72 h), first-order attribution to the reseller and the source delegate, history, document orchestration (invoice and delivery note), free replacement orders created from after-sales claims, and returns (V1): request on a delivered order, back-office decision, reception that restocks automatically and triggers the credit note (ORD-13).

Transactions it opens: confirmation reserves stock (inventory), checks credit (billing) and creates the delivery record (fulfillment); cancellation releases or re-enters stock; return reception posts RETURN movements and asks billing for the credit note — all in the same commit as the status change.

Risks:

• The transition table must be exhaustive per actor; property tests generate every (status, actor, action) triple.
• Concurrent back-office confirmation and reseller cancellation: row lock plus version; the loser gets 409 ORDER_TRANSITION_NOT_ALLOWED or 409 VERSION_CONFLICT.
• Assisted-order expiry against a late confirmation: the confirmation checks assistedExpiresAt in its own transaction (409 ASSISTED_ORDER_EXPIRED), so the job's 15-minute granularity never matters.
• The confirmation queue is now on the critical path of every order: its size and age are monitored (analytics), and validators get in-app and SSE alerts.

fulfillmentCopy Anchor Link

Delivery records per order (mirroring the order from VALIDATED on), preparation and picking lists, carrier assignment (own fleet or carrier company) and tracking numbers, proof of delivery (photo, recipient), failed deliveries, the delivery-fee policy, and the carrier and tracking of a return's way back when HOCO collects it. V2 adds carrier APIs.

Risks:

• Two status fields (order and delivery) can drift: orders is the only writer of order status and updates the delivery in the same transaction.
• Proof photos are taken on warehouse devices through the web uploader; the private bucket and signed URLs apply.

billingCopy Anchor Link

Invoices generated from orders with legal mentions and PDF, invoice statuses, payment recording, reseller payment declarations with proof and their verification, allocation of payments to invoices, credit accounts (limit, used, available) and the credit check used at checkout and confirmation, the reseller finance summary, and credit notes (V1, FIN-08) issued for return receptions and after-sales CREDIT_NOTE resolutions. V2 adds payment terms and due dates, reminders and accounting export.

Risks:

• Legal numbering: FAC- and credit-note numbers come from a transactional NumberSequence row lock, gapless per year.
• Legal mentions (NIF, NIS, RC, AI, VAT) and layout come from DQA-09; PDFs are rendered by the worker from the stored snapshot, never from live data.
• Financial data is restricted (ACL-04): DTOs drop purchase prices and margins without finance or pricing permissions.

loyaltyCopy Anchor Link

V2. The points ledger (append-only), earning rules (on delivery or payment per setting), bonuses, expiry, reversals on cancellation and returns, levels Bronze, Silver, Gold, VIP over a period with HOCO's thresholds, the rewards catalogue, redemptions and vouchers usable at checkout (cahier §4.6, §5.5).

Risks: the policy itself is an open decision of the cahier (§15 « politique de fidélité »); reversing points already redeemed needs a rule (negative balance or debt).

fieldCopy Anchor Link

Everything the delegate does and the back-office plans: delegate profiles, objectives per period, tour planning (daily, weekly or monthly series; ordered stops, imposed or recommended; priorities and time slots), the tour lifecycle (only the assigned delegate starts), visits with GPS check-in tolerance, checklists, notes, photos, structured reports that create follow-ups, not-done reasons, visit locking and unlocking, the closing summary and KPIs, location pings and trails, live follow-up, the recommended order (nearest neighbour), visit types and checklist templates, the delegate home and performance aggregates.

A visit report that plans a next action creates the follow-up through crm.upsertFollowUpFromReport() in the same transaction; the task id comes back in the response (or the replayed item's result), and the delta feed brings the task to the device.

Risks:

• The largest module (SRV-21, size L): offline semantics, GPS accuracy in dense centres and indoors, battery, and privacy (no position outside a tour — ADR-016).
• KPIs computed from data that arrives up to 72 h late: tour summaries are recomputed when late visits arrive, and the daily aggregates rebuild the last three days.

invitationsCopy Anchor Link

Invitation codes (8 characters, no ambiguous letters), signed links and QR payloads, share texts, share tracking, attribution of installs (Play install referrer on first open, code typed at sign-up) and the activation funnel: sent → app installed → account created → phone verified → catalog viewed → first order (IVT-03).

Risks:

• No install referrer on iOS: attribution relies on the code at sign-up.
• Brute force on the public resolve endpoint: 30 requests per minute per IP, and the 8-character alphabet gives about 10^12 codes.
• The landing /i/{code} and /.well-known/assetlinks.json are served by the reseller web: a web outage breaks invitation links, so the landing is covered by the uptime monitor (architecture).

supportCopy Anchor Link

Reseller tickets (type, related order, messages, attachments, statuses), back-office handling (assignment, internal notes, replies, statuses), and since the product decisions after-sales claims in V1 (SUP-04): a ticket of type AFTER_SALES names the order, the claimed lines and quantities (TicketItem), the issue (AfterSalesIssue) and photos; the back-office diagnoses and resolves it with an AfterSalesResolution:

The module also owns support regions (SUP-05, ADM-08): wilayas grouped into regions, each with a WhatsApp number and hours. support.whatsapp resolves the caller's region from the wilaya declared on their account, else from the device position (geo.nearestCommune() → wilaya → region), else from a wilayaCode picked by the user, else the default number. Announcements to delegates or resellers with targeting and schedule (« Messages ») complete the module.

Risks:

• Internal notes leaking to resellers: a visibility flag on TicketMessage and separate DTOs, covered by contract tests.
• A claim on lines already claimed or returned: claimed quantity plus returned quantity can never exceed the delivered quantity (checked in the claim and return transactions).
• Region resolution from a position needs commune centroids for every commune in the seed; without a match the user gets the wilaya picker, never an error.

notificationsCopy Anchor Link

Turns domain events into notifications: the event → channel → recipient matrix (NotificationRule), localised templates per event, channel and locale, user preferences (TRANSACTIONAL and SECURITY cannot be disabled), the in-app inbox, delivery through push (FCM), SMS and e-mail (V2 WhatsApp Business), the delivery log and retries — and the two SSE streams: the back-office stream and each user's own stream (ADR-008). It also sends the silent "sync hint" pushes requested by sync.

Risks:

• SMS cost and deliverability: SMS only where the matrix says so (OTP, account decisions, critical order events), never for promotions.
• Notification fatigue: dedupe per (event, recipient, channel) and daily digests for follow-ups and stock alerts.
• FCM token churn: tokens reported invalid by FCM are deactivated at once.
• Long-lived SSE connections: heartbeats, Traefik timeouts above 60 s, and one Redis consumer per api instance.

analyticsCopy Anchor Link

KPI and chart queries with permission-aware filters, dashboard layouts per role, daily aggregates and their rebuild for late offline data, the essential report catalogue, asynchronous exports (PDF, XLSX, CSV), global back-office search (fan-out to each module's search function, filtered by permission), the delegate performance aggregates, and monitoring of the confirmation queue (count and age of orders to confirm). V2 adds advanced analytics.

Risks:

• Dashboard latency on large ranges: aggregates for history, live queries only for "today".
• Numbers of the last three days move as offline data lands: those days are marked provisional on the dashboards.
• Large exports: streamed XLSX/CSV generation in a sandboxed worker process, row limit per export.

filesCopy Anchor Link

Upload sessions (pre-signed PUT valid 10 minutes), completion checks (size, type and purpose rules of FilePurpose), metadata stripping and thumbnails in the worker, private downloads through signed GET URLs valid 5 minutes after an access check against the owning record, public assets on the public bucket, storage of generated documents, orphan cleanup.

Risks: a pre-signed PUT cannot cap the size, so completion verifies it and deletes oversize objects; polymorphic ownership makes the access check the most security-sensitive code of the module — one function per owner type, tested per role.

auditCopy Anchor Link

The activity journal (AUD-01, cahier §10): logins, creations, modifications, validations, exports, deletions, permission changes and overrides, with actor, time, app, IP or device, entity and a before/after diff. Entries are written inside the business transaction (ctx.audit()), never through events.

Risks: volume (indexes on entity and on actor + time), personal data in diffs (passwords and tokens never logged, phones masked in diffs), tamper resistance (the application role has no UPDATE grant on the table, and DELETE only through the retention job's role).

settingsCopy Anchor Link

Typed business parameters grouped by domain with validation and audit (ADM-03), reference lists by listKey, app version policies and maintenance mode (ADM-07), the public app configuration, and business number sequences (REV, CMD, FAC, BL, PAY, TRN, VIS, TKT, RET).

Risks: one Zod schema per setting key in the contract (unknown keys rejected, defaults explicit); number allocation serialises writers on one row per (type, year) — acceptable at HOCO's volume; reference items in use are deactivated, never deleted.

syncCopy Anchor Link

The server side of offline sync for the delegate app (offline sync design): idempotency records and the idempotency middleware every mutation passes through, ordered batch replay with per-item results, the delta feed with tombstones derived from history (no tombstone table), the location-ping route (stored by field), occurredAt plausibility, and sync hints (silent pushes) when the back-office changes something in a delegate's scope.

Risks: see the offline sync design — conflict rates, late data, devices with wrong clocks.

jobsCopy Anchor Link

The asynchronous backbone: queue registry (names and default options), BullMQ connections, the worker bootstrap, job schedulers (cron in Africa/Algiers), the transactional outbox (emit() helper and dispatcher), the event subscription registry, dead-letter handling and replay tooling, queue and outbox metrics, the backup verification ping.

Risks: Redis persistence (AOF, noeviction), outbox lag, poison events, overlapping cron runs — all handled on Jobs and scheduler.

integrationsCopy Anchor Link

Adapters (ports) for every external system, each with a development simulator: SMS gateway (SIMULATE_SMS), SMTP e-mail (Mailpit locally), FCM, maps geocoding, the S3 client. It also runs data imports — products, resellers, users, stock — from Excel/CSV templates with a dry-run validation report, idempotent apply and an error-rows export (ADM-06, CAT-06); imported rows go through the owning modules' services. V2: carrier APIs, WhatsApp Business, ERP/accounting exchange, stock-system sync.

Risks: providers not chosen yet (costs and quotas to validate, INT-07); initial data quality from HOCO's spreadsheets (phones that do not normalise, duplicates, customer types missing) — the dry-run report is the gate before go-live (LCH-01).

Events catalogueCopy Anchor Link

Every event is an OutboxEvent row written in the transaction of the change (ADR-007) — except delegate.position, which is ephemeral (see below). The envelope is the same for all (the OutboxEvent row as handlers see it; its id is also the SSE event id):

{
  "id": "01935c4e-8a1f-7c3e-9b2a-4f6d8e0a1b2c",
  "eventKey": "order.validated",
  "v": 1,
  "aggregateType": "Order",
  "aggregateId": "01935c4d-1e2f-7a9b-8c3d-5e6f7a8b9c0d",
  "occurredAt": "2026-11-03T08:12:00Z",
  "actor": { "userId": "01935a10-2b3c-7d4e-9f50-6a7b8c9d0e1f", "app": "DASHBOARD" },
  "requestId": "req_01J9Z4K7M2",
  "payload": { "orderId": "01935c4d-1e2f-7a9b-8c3d-5e6f7a8b9c0d", "number": "CMD-2026-000158", "resellerId": "01935b22-3c4d-7e5f-8a6b-7c8d9e0f1a2b" }
}

Payloads carry ids, business numbers and the few values consumers need to route or render (status, amounts in centimes, reason codes); consumers load anything else from the owning module. Which events notify whom, on which channel, is the job of the notifications matrix; the consumers listed below are the modules that react.

delegate.position is the one event that bypasses the outbox: one ping every 5 minutes per delegate is low-value and last-value-wins, so after the LocationPing insert commits, the api publishes it straight to the back-office stream. A lost position is replaced by the next one.

SSE projectionCopy Anchor Link

Both streams carry a small set of stable types derived from domain events; clients ignore types they do not know, so types can be added without breaking anyone. The authoritative lists are on admin.events.stream and events.stream.

Back-office stream — GET /v1/admin/events, filtered by permission; events are invalidation hints.

Own stream — GET /v1/events, routed to the recipients of each event (the reseller's users; the delegate for assisted orders); events carry the new state.

The own stream never carries back-office-only data (internal notes, purchase prices, other resellers). Both streams send resync when Last-Event-ID is older than their retention window.