Architecture

The HOCO ecosystem is one central API and one database serving four interfaces — the cahier's founding principle: « Les trois solutions utilisent une API centrale sécurisée et une base de données unique » (cahier §2). This page shows the system from the outside in (C4 levels 1 and 2), the two repositories, how a request travels, where everything runs, and the decisions behind it. The inside of the server is on Architecture and data and the service catalogue.

System contextCopy Anchor Link

Who uses the platform and which external systems it depends on (C4 level 1). External services are « à confirmer » in the cahier (§11); their costs and quotas must be validated by HOCO (INT-07).

ContainersCopy Anchor Link

What runs where (C4 level 2). Every arrow into the API carries the caller's session; nothing but the API touches the database.

The server's internal structure (24 modules, middleware chain, data ownership) is level 3; see Architecture and data and the service catalogue.

RepositoriesCopy Anchor Link

Two repositories (ADR-001). Their only contract is the OpenAPI 3.1 document exported from packages/contracts through the server.

Request pathsCopy Anchor Link

Every client talks to https://api.hoco.dz/v1 (staging api-staging.hoco.dz; the domain is a working assumption until HOCO confirms it). Conventions are on the API reference.

There are two streams with the same mechanics. The back-office stream carries operational events filtered by permission; the own stream carries only the caller's events — the status changes of their orders, assisted orders awaiting their confirmation, replies to their tickets, their returns, new inbox notifications (ORD-15, SYN-07). Push notifications still go out for the same changes, so a closed app is informed too.

The back-office live stream, from the domain change to the operator's screen (the own stream works the same way, filtered by recipient instead of permission):

The back-office stream is permission-filtered per connection and its events are invalidation hints: the dashboard refetches the affected queries, except delegate.position, which carries the position itself. The own stream carries the new status and timestamp so an order screen can update without a round-trip. The event types of both streams and their mapping to domain events are listed in the SSE projection; the endpoints are admin.events.stream and events.stream.

Deployment topologyCopy Anchor Link

Four environments (cahier §13.1 asks for development, pre-production / recette client and production; staging is added for continuous integration). Ports in development: server 3100, dashboard 3101, web 3102, docs 3103.

Assumption — the dashboard is served at admin.hoco.dz and the reseller web at app.hoco.dz (the invitation link https://app.hoco.dz/i/AB12CD34 is canonical); staging and pre-production hostnames follow <app>-staging / <app>-preprod. Final domains are decision D-12.

Backups, restore drills, RTO/RPO, monitoring and the release procedure are on Deployment and operations.

Architecture decision recordsCopy Anchor Link

Each record states the context, the decision, the alternatives that were weighed and the consequences. A record is never edited to say something else: a later decision supersedes it with a new record that links back.

ADR-001 — Two repositories: a TypeScript monorepo and a Flutter monorepoCopy Anchor Link

Context. Five deliverables in two stacks. Anis builds the server, back-office, reseller web, docs and DevOps in TypeScript; Imad builds the reseller and delegate apps in Flutter. The two Flutter apps share a lot (design system, generated API client, catalog and cart widgets, offline engine), as do the TypeScript apps (contracts, UI kit, env, helpers). Tooling differs completely: pnpm + Turborepo + Biome versus pub workspaces + Melos + flutter analyze, and Android signing in CI. The only hard coupling between the stacks is the API contract.

Decision.

• AnisBetehi/hoco holds apps/server, apps/dashboard, apps/web, apps/docs and packages/config, env, db, contracts, api-client, ui, shared.
• hoco-mobile (Imad's GitHub account) holds apps/reseller, apps/delegate and the hoco_* packages.
• The interface is the OpenAPI 3.1 document produced by pnpm openapi:export, tagged with each contract version; hoco_api is regenerated from a pinned version, never from a moving target.
• Contract changes are reviewed by Imad as the first consumer (the CODEOWNERS rule for /packages/contracts/ is already prepared).

Alternatives considered.

• One polyglot monorepo — contract and Dart client could change in one PR, but two toolchains in one root, slower CI on every change, and blurred ownership. Turborepo does not orchestrate Dart tasks.
• One repository per app — the two Flutter apps would duplicate hoco_ui, hoco_api and the offline engine, or publish them as versioned packages: more ceremony for a team of two developers.

Consequences.

• Each developer owns a repository, its CI and its conventions; branch model and commit rules are the same on both sides (workflow).
• A contract change is two PRs (contract first, then clients), sequenced by the API-contract workflow and its changelog; the mock server lets mobile work start before the server implementation.
• Continuity risk: the mobile repository sits on a personal account. Before go-live HOCO gets admin access, and the repository, the upload keystore and the Play Console ownership move to an organisation account controlled by HOCO or the team (D-25).

Status. Accepted.

ADR-002 — REST + OpenAPI 3.1, contract-first with oRPC instead of tRPCCopy Anchor Link

Context. Four clients, two of them in Dart. The TypeScript apps want end-to-end types; Flutter needs plain REST and a generated client; the team wants a mock server the day the contract exists (M04 — API contract v1 published) and one schema per operation for validation, types and documentation. Zod 4 is already the validation library.

Decision.

• Every operation is declared in packages/contracts with oRPC's contract builder: .route({ method, path }) relative to /v1, Zod input and output, declared errors, and metadata (permission key, scope, idempotency requirement, release).
• apps/server implements the contract and serves it with oRPC's OpenAPI handler mounted in Express under /v1; /openapi.json is generated from the contract and /reference (Scalar) is enabled outside production.
• @hoco/api-client uses oRPC's OpenAPI link, so the Next apps send exactly the REST requests the Flutter apps send, plus TanStack Query helpers.
• Flutter generates hoco_api from the exported document; Prism serves it as a mock.

Alternatives considered.

• tRPC — excellent for TypeScript-only clients, but its procedure protocol is not REST, OpenAPI is an add-on, and Dart cannot consume it. Rejected.
• Hono + @hono/zod-openapi — good OpenAPI output, but routes and implementation live together; no separate contract package to generate the TypeScript client from before the server exists.
• ts-rest — the same contract-first idea; smaller ecosystem around OpenAPI 3.1 and TanStack Query.
• NestJS + Swagger decorators — heavier runtime, decorator metadata as the source of truth, a second validation layer.
• GraphQL — flexible reads, but HTTP caching, offline replay and per-field authorisation get harder for a CRUD-heavy domain.

Consequences.

• One schema drives validation, TypeScript types, the OpenAPI document, the Dart client and these docs.
• Discipline: nothing is implemented before it is in the contract; the contract package must not import server code.
• The OpenAPI output must express Zod faithfully (integers, ISO date strings, discriminated unions); the mobile CI regenerates hoco_api on each contract tag to catch generator surprises early.
• Breaking changes follow the /v1 policy of the API reference; diffing the exported document between versions in CI (e.g. with oasdiff) is recommended.

Status. Accepted.

ADR-003 — One central API; the Next.js apps are pure clientsCopy Anchor Link

Context. The cahier requires one secured central API and one database (§2). Price resolution, stock, credit, scopes and lifecycles must behave identically in the mobile apps, the reseller web and the back-office, and the reseller web may not have web-only rules (RWA-02). Next.js makes it tempting to read the database from Server Actions — the team's previous project did exactly that.

Decision.

• All business logic and all data access live in @hoco/server.
• @hoco/dashboard and @hoco/web render UI and call the API: from the browser (CORS + cookie) or from server components and route handlers (server-to-server, forwarding the user's cookie).
• They never depend on @hoco/db, never hold credentials for the database, storage or providers, and implement no rule beyond presentation: formatting, and hiding actions the user lacks permissions for (from me.get), which the API re-checks anyway.

Alternatives considered.

• Next.js full-stack (Server Actions + Prisma) for the web apps plus a separate API for mobile — every rule implemented twice; drift guaranteed. Rejected.
• A backend-for-frontend per client — an extra hop and duplication with no need at this scale. Rejected for V1.

Consequences.

• One place to secure and test: the permission sweep of SRV-28 covers every client at once, and parity between mobile and web is structural.
• Every screen waits for its contract operations; the mock server and the contract-first workflow absorb that.
• Server rendering depends on API latency, kept low by calling it over the internal Docker network.
• Enforcement: @hoco/db is not a dependency of the Next apps, and a lint rule forbids importing it outside apps/server and packages/db (dependency rules).

Status. Accepted.

ADR-004 — Modular monolith with a separate worker process from one imageCopy Anchor Link

Context. One backend developer, 24 cohesive domains, invariants that span modules (checkout touches pricing, promotions, stock and credit), CPU-heavy or slow work (PDF rendering, exports, imports, image processing, SMS), scheduled jobs and long-lived SSE connections.

Decision.

• @hoco/server is a modular monolith of 24 modules under apps/server/src/modules/<name> with enforced boundaries (service catalogue).
• It runs as two processes built from the same image (docker/app.Dockerfile, APP=server):
  • api — HTTP: REST, OpenAPI, SSE; applies migrations at start (docker/start.sh);
  • worker — BullMQ processors, job schedulers, outbox dispatcher; no public HTTP.
• The role is chosen at runtime: start.sh gets an APP=worker branch that starts src/worker.ts without migrating.

Alternatives considered.

• Microservices — network calls and distributed transactions for invariants that are one SQL transaction today; operational load far beyond a team of one backend developer.
• Serverless functions — SSE, BullMQ workers and Prisma connection management fit poorly.
• A single process for HTTP and jobs — a 50 000-row export or a PDF burst would degrade API latency, and every restart would couple both.
• A separate worker codebase — duplicates module code or forces a shared library split.

Consequences.

• In-process service calls; one database transaction where an invariant requires it.
• The API and the worker restart and scale independently. V1 runs one replica of each; BullMQ, the advisory-lock-elected outbox dispatcher and idempotent schedulers allow more workers later (jobs and scheduler).
• Module boundaries rely on conventions plus lint rules; violations are review blockers.
• Job payloads are versioned (name + v) because an old worker can briefly run beside a new api during a deploy.

Status. Accepted.

ADR-005 — Better Auth with phone number and bearer plugins; cookies for the webCopy Anchor Link

Context. Resellers and delegates sign in with phone + password (cahier §6), sign-up and password reset use SMS OTP (§11), staff sign in with e-mail or phone. The cahier requires expiry, revocation and attempt limiting (§10). Mobile needs bearer tokens; the two web apps need an httpOnly cookie usable from admin. and app. subdomains. Suspending an account must cut access at once (SEC-06).

Decision.

• Better Auth runs inside @hoco/server (identity module) with the Prisma adapter on User, Session, Account, Verification:
  • phone-number plugin: OTP send/verify, phone + password sign-in;
  • bearer plugin: mobile Authorization: Bearer;
  • e-mail + password for staff.
• Sessions are opaque and database-backed, so they can be revoked; Redis is the secondary storage for session lookups and rate-limit counters.
• Cookies: Domain=.hoco.dz; Secure; HttpOnly; SameSite=Lax, with an environment-specific prefix (hoco in production, e.g. hoco_stg in staging), so staging and production cookies — which share the parent domain — never collide. trustedOrigins = CORS_ORIGINS.
• Durations: 30 days sliding for resellers and delegates; 7 days sliding for staff with re-authentication for sensitive actions (decision to confirm).
• /v1/auth/* operations are contract procedures that call Better Auth's server API, so authentication is in the same OpenAPI document as everything else.
• Guests. Catalog operations, promotions and banners, support.whatsapp and the public invitation operations are auth: optional or public: the session step resolves a session when one is sent and otherwise continues as a guest, rate-limited per IP. The catalog then returns price: null and refuses cart operations (AUTH-10).
• Customer type. Reseller sign-up records the declared customer type (SUPER_GROS, DEMI_GROS, DETAIL) on the reseller; only the back-office changes it later, audited (AUTH-11).
• Lockout (5 failures → 15 minutes per phone + IP) and OTP limits (1 per 60 s, 5 per hour; 6 digits; 5 minutes; 5 attempts) are enforced in the identity module.

Alternatives considered.

• Auth.js — web-first; bearer sessions for native apps are awkward.
• Lucia — deprecated as a library.
• Firebase Auth or Supabase Auth — external identity provider: per-SMS phone-auth costs, lock-in, data location, and the API would still need its own authorisation layer.
• Keycloak — heavy to operate for one VPS.
• Hand-written JWT — security risk, and stateless tokens cannot be revoked immediately.

Consequences.

• Revocation on suspension, password change and from the sessions list (auth.sessions.revoke, admin.users.sessions).
• One session model for all apps; the request pipeline resolves either header or cookie (request lifecycle).
• Better Auth versions are pinned and auth flows have integration tests, because upgrades follow its release cadence.
• A browser keeps one session per environment: a person holding both a staff and a reseller identity needs two browser profiles — accepted and documented.

Status. Accepted; staff session length and two-factor authentication to confirm (D-33).

ADR-006 — PostgreSQL 17 + Prisma 7; UUIDv7 ids; client-generated ids for offline recordsCopy Anchor Link

Context. A relational domain with hard invariants (stock never oversold, credit ceilings, gapless invoice numbers, lifecycles), reporting queries, one database for everything (§2), and offline creation in the delegate app that needs ids before the server has seen the record.

Decision.

• Database. PostgreSQL 17 (postgres:17-alpine locally on :5442).
• ORM. Prisma 7 with the prisma-client generator (ESM output in packages/db/prisma/generated), the @prisma/adapter-pg driver adapter and a multi-file schema (packages/db/prisma/schema/*.prisma, one file per domain).
• Migrations. Applied by prisma migrate deploy when the api container starts.
• Ids. Primary keys are UUIDv7 (@default(uuid(7))); human-readable business numbers are separate fields from NumberSequence.
• Client-generated ids. For offline-creatable records — field prospects (Reseller), unplanned visits, visit photos, visit reports, notes (Interaction), store photos and their File rows — the client supplies the UUIDv7 and the server upserts on it (offline sync design).
• Search. Extensions pg_trgm and unaccent for catalog search.
• Geography. No PostGIS in V1: coordinates are lat / lng doubles, distances use haversine, map clustering uses a grid; to revisit with V2 tour optimisation.

Alternatives considered.

• MySQL/MariaDB — weaker partial indexes, JSON and full-text search.
• MongoDB — invariants and reporting harder.
• Serial integer ids — enumerable, require a round-trip before creation, unusable offline.
• UUIDv4 — random B-tree inserts.
• Drizzle or Kysely — viable; Prisma kept for team precedent and the multi-file schema.

Consequences.

• Ids can be minted anywhere without coordination, insert in time order, and make offline creates naturally idempotent.
• Client ids are validated (version 7, embedded time at most 5 minutes in the future, unique) and never trusted for authorisation.
• Migrations must be backward compatible with the previous release (expand, migrate, contract) because the old container serves while the new one starts.
• Interactive transactions have a 10-second budget and never contain network calls.

Status. Accepted.

ADR-007 — Transactional outbox + BullMQ for asynchronous workCopy Anchor Link

Context. Important events must produce notifications and journal entries (cahier §2.1), update the back-office live view, drive CRM lifecycle automation and refresh analytics — reliably and without slowing requests. Writing to the database then enqueueing to Redis loses the event if the process dies in between.

Decision.

• Emit. Services call ctx.emit(event) inside their transaction; the event is an OutboxEvent row committed with the change.
• Dispatch. The worker's dispatcher wakes on LISTEN/NOTIFY and polls every second as a safety net. It publishes the SSE projection and enqueues one BullMQ job per subscribed handler into the events queue, deduplicated by job id (event id + handler).
• Infrastructure. Redis 7 (AOF on, noeviction) backs BullMQ. Job schedulers run the cron jobs in Africa/Algiers.

Alternatives considered.

• Enqueue after commit — loses events on crashes.
• A Postgres-only queue (pg-boss, Graphile Worker) — viable with fewer moving parts. Not chosen because Redis is needed anyway (rate limits, session cache, SSE fan-out) and BullMQ brings rate-limited queues, schedulers and tooling.
• Kafka / RabbitMQ — operational overkill.
• Logical decoding (Debezium) — complex for the gain.

Consequences.

• No lost events; request latency unaffected; dispatched events stay replayable for 30 days.
• Delivery is at-least-once, so every handler is idempotent and tolerant of reordering.
• Redis becomes stateful infrastructure to persist and monitor; outbox lag is an alerting signal (over 30 s for 5 minutes).

Status. Accepted. Queues, dispatcher and every scheduled job: Jobs and scheduler.

ADR-008 — Server-Sent Events for real-time: a back-office stream and each user's own streamCopy Anchor Link

Context. The back-office must show new orders, orders to confirm, status changes, check-ins, tour starts and closings, delegate positions, stock alerts, pending accounts, returns and after-sales claims as they happen (SYN-07, FLD-13; cahier §5.3 « apparaît immédiatement dans le back-office », §6.4 « en temps réel »). Since the product decisions of 17 Oct 2026, every order status change must also reach the reseller live in the app and on the web, and as a notification (ORD-15). Traffic is one-way, server to client: a few dozen staff sessions and, at peak, a few hundred open reseller screens.

Decision.

• Two streams, one mechanism.
  • GET /v1/admin/events (admin.events.stream): the back-office stream, filtered per connection by the user's permissions.
  • GET /v1/events (events.stream): the caller's own stream — order status changes and modifications, assisted orders awaiting their confirmation, ticket replies, return status changes, new inbox notifications — opened by the reseller app while in the foreground and by the reseller web while a page is open.
• Authentication. The session cookie in the browsers; Authorization: Bearer from the Flutter SSE client (the reseller app does not use the browser EventSource).
• Contents. Event types are a small, stable projection of domain events (SSE projection). Back-office events are invalidation hints (the dashboard refetches); own-stream events carry the new status, so the order screen updates without a round-trip.
• Fan-out and resume. The SSE event id is the OutboxEvent id. The worker publishes each projected event on Redis; every api instance subscribes and routes it to its local connections, by permission or by recipient. On reconnect, Last-Event-ID replays the events dispatched since from the outbox table (at most 500 events or 24 h); beyond that the server sends a resync event and the client refetches. delegate.position is sent without an id: the next position replaces it.
• Liveness. A heartbeat comment every 25 s keeps proxies from closing idle connections.
• Push stays. SSE only serves open screens; every status change still produces the push and inbox notification from the notifications matrix. The delegate app relies on push (including silent sync hints) and GET /sync/delta.

Alternatives considered.

• WebSockets — bidirectional capability nobody needs, plus upgrade authentication, sticky sessions and proxy tuning.
• Polling — every widget of every open screen polling every few seconds is wasteful and still laggy for the live map and order tracking.
• Push only for resellers — not live while the app is open (delivery delays, notifications muted), and nothing on the web.
• A hosted realtime service (Pusher, Ably) — cost, and operational data leaves the platform.

Consequences.

• Native reconnection and resume in browsers; the same protocol from Flutter; works through Traefik on HTTP/1.1 and HTTP/2.
• One long-lived connection per open screen; one Redis subscription per api instance for both streams.
• The reseller app closes its stream when it goes to the background, to save battery and avoid Android background limits.
• A missed event costs a refetch, never an inconsistency: the REST resources stay the source of truth.

Status. Accepted.

ADR-009 — S3-compatible object storage with pre-signed uploadsCopy Anchor Link

Context. Store, visit and delivery photos; store documents (RC, NIF, ID); payment proofs; ticket attachments; generated PDFs; exports; import files; product images (cahier §11, §10 « Protection des documents et fichiers téléchargés »). Uploads come from phones on weak networks; the API should not proxy bytes.

Decision.

• Buckets. Two per environment: S3_BUCKET_PUBLIC for product images, brand logos and banners, served through a public base URL or CDN; S3_BUCKET_PRIVATE for everything else.
• Upload. files.createUpload returns a pre-signed PUT valid 10 minutes; the client uploads directly; files.completeUpload checks size, type and purpose, then the worker strips metadata and makes thumbnails.
• Private reads. Signed GET URLs valid 5 minutes, issued after an access check on the record that owns the file (file flows).
• Keys. Object keys carry no personal data.
• Provider (decided 18 Oct 2026). A MinIO instance on the VPS in every environment (locally :9100, console :9101), accessed through the S3 API. MinIO shares the server's failure domain, so its buckets are backed up off the VPS nightly with the database.

Alternatives considered.

• Files in the database — bloats tables and backups.
• Multipart uploads through the API — API memory and bandwidth, timeouts on weak networks.
• Provider-specific features — lock-in.

Consequences.

• The API stays light, and any S3-compatible provider works.
• A pre-signed PUT cannot cap the size, so the size is verified at completion and oversize objects are deleted.
• Abandoned uploads are purged by a daily job; protecting the private bucket (versioning or replication) is part of the backup plan.

Status. Accepted; provider pending.

ADR-010 — Offline-first delegate app: local database, idempotent outbox, delta pullsCopy Anchor Link

Context. The delegate app must keep a tour, visits, notes and photos locally under weak network; a sync queue handles retries, duplicates, errors and conflicts; the user sees synchronisé, en attente or en erreur (cahier §7.3, SYN-04…SYN-06). Resellers order from shops where a live price, stock and credit check is required anyway.

Decision.

• The delegate app is offline-first:
  • a drift database holds its offline scopes;
  • an outbox holds mutations, each with its own Idempotency-Key and occurredAt, replayed in order through POST /sync/batch;
  • GET /sync/delta pulls the changes for its scopes;
  • photos go through an upload queue.
• The reseller app and web are online-first with read caches: no offline ordering. They can be browsed as a guest (no prices, no cart) and keep order screens live over SSE (ADR-008).
• What is offline-capable, the conflict catalogue and the replay rules are in the offline sync design; the client side is on mobile offline sync.

Alternatives considered.

• An online-only delegate app — fails §7.3.
• Generic bidirectional replication (CouchDB, PowerSync, ElectricSQL) — third-party infrastructure, per-scope authorisation pushed into sync rules, business rules bypassed.
• Offline ordering for resellers — stale prices, stock and promotions at submission. Rejected.

Consequences.

• Field work survives coverage gaps.
• Every delegate mutation is idempotent and replay-safe, and conflict codes are part of the contract.
• A sync centre screen (DA-27) and a real field test (MOB-13) are required.

Status. Accepted.

ADR-011 — Money in integer centimes; timestamps in UTC; business days in Africa/AlgiersCopy Anchor Link

Context. DZD amounts with 19 % VAT by default; floating-point drift is unacceptable on invoices. The business day is Algerian time (UTC+1, no DST). Devices may have wrong clocks, and reports and objectives are per day.

Decision.

• Money is an integer number of centimes of DZD everywhere — database, API, apps — with currency: "DZD" on orders and invoices. Rates (VAT, discounts) are basis points (1900 = 19 %).
• Arithmetic stays in integers with one rounding helper (half up, to the centime) in @hoco/shared; display goes through formatDzd() (125000 → 1 250,00 DA), identical on server and browsers.
• Timestamps are timestamptz, exchanged as ISO-8601 with Z; date-only fields are YYYY-MM-DD.
• Business days. "Today", tour days, objective periods, report days and cron schedules are computed in Africa/Algiers by shared helpers.

Alternatives considered.

• Decimal libraries in JavaScript — serialisation pitfalls and weight for no gain over integers.
• Floats — rejected.
• Local-time storage — ambiguous across servers and devices.

Consequences.

• Exact totals and reproducible documents.
• Column widths are chosen per field in the database design: a 32-bit integer stops at 21 474 836,47 DA.
• The VAT rounding basis (per line or per document) is a business rule (business rules).
• Day boundaries are tested around 23:00–01:00 UTC.

Status. Accepted.

ADR-012 — Docs-as-code in the monorepo, hosted on the VPSCopy Anchor Link

Context. Requirements, API catalogue, screen inventory and plan must stay consistent with each other and with the code, and be shared with HOCO and the team. Plan dates come from a scheduler and must never be typed by hand.

Decision.

• apps/docs (Fumadocs on Next.js) lives in the monorepo.
• Canonical data is JSON (content/spec/*.json, content/plan/tasks.json) rendered by components; team-task pages are generated from the plan.
• MDX is compiled in CI (check-mdx).
• The site is deployed later on the VPS with the other apps (Dokploy); until then the team runs it locally.
• Access is restricted to the team and HOCO because the site holds client and planning information.

Alternatives considered.

• Notion or Confluence — drift from the code, no data-driven tables.
• GitHub wiki — no components, weak structure.
• Docusaurus — fine, but Fumadocs matches the Next.js and Tailwind stack.
• A separate hosting provider — one more account and bill for a small internal site; the VPS already runs everything else.

Consequences.

• Changes are reviewable, and dates, requirements and endpoints have one source.
• Writers follow the MDX rules of apps/docs/AUTHORING.md.
• Once SRV-03 publishes the contract, the OpenAPI document becomes authoritative for operations and these pages follow it.

Status. Accepted.

ADR-013 — Dokploy on a VPS for the server, dashboard and reseller webCopy Anchor Link

Context. A small team and a cost-sensitive client; three environments required (§13.1) plus staging; automatic backups with tested restores (§10, SEC-05); managed TLS; simple deploys; a possible data-residency constraint from Law 18-07 (SEC-08).

Decision.

• Platform. Dokploy (open-source PaaS: Docker Swarm + Traefik) on two VPS: production alone on one, staging and pre-production as two Dokploy projects on the other.
• Services. Each environment runs api, worker, dashboard, web, plus PostgreSQL 17 and Redis 7 as Dokploy database services with scheduled backups to off-site S3.
• Build and release. Images come from docker/app.Dockerfile with the APP build argument; staging deploys every push to dev, production deploys release tags from master.
• TLS. Traefik with Let's Encrypt.

Alternatives considered.

• Managed PaaS (Render, Fly.io, Railway) — monthly cost per service, no Algerian region, data location.
• Kubernetes — operational overkill.
• Raw docker compose with scripts — no UI, manual TLS and rollbacks.
• Coolify — comparable; team precedent favours Dokploy.
• An Algerian cloud provider — remains possible as the host for Dokploy if residency requires it.

Consequences.

• Low cost, full control, and the same recipe in every environment.
• A single VPS is a single failure domain: backups, a written restore runbook and stated RTO/RPO targets are mandatory (deployment and operations).
• OS patching and monitoring are the team's job (OPS-04).
• The VPS provider and country are decided with HOCO (D-15).

Status. Accepted; VPS provider and location pending.

ADR-014 — French first; internationalisation and RTL ready from day oneCopy Anchor Link

Context. « Français en V1 ; arabe et anglais prévus selon validation » (cahier §9, NFR-06). Arabic means right-to-left layouts; retrofitting i18n is expensive.

Decision.

• Apps. No user-facing string is hard-coded: next-intl catalogs fr (default), ar, en in the Next apps; ARB files in hoco_l10n for Flutter.
• API. Messages are localised from Accept-Language (French by default) while error codes stay stable; notification templates exist per event × channel × locale; users keep a locale preference.
• Layout. Logical start/end CSS properties and mirrored directional icons.
• Data. Reference data carries French and Arabic names (wilayas, communes). Product content stays French-only in V1.

Alternatives considered.

• French hard-coded — cheap now, expensive later.
• Runtime machine translation — quality and cost.

Consequences.

• Adding Arabic becomes translation plus RTL QA, not refactoring.
• Every change adds keys in three catalogs (French filled, others placeholders), with a missing-key check.
• RTL is verified on key screens (MOB-17).

Status. Accepted.

ADR-015 — Maps provider: Google Maps proposed, pending HOCO's decisionCopy Anchor Link

Context. The cahier lists « Google Maps, Mapbox ou service équivalent pour adresses, itinéraires et géocodage » (§11, INT-01). Needs: the delegate's map with stops and current position, hand-off to turn-by-turn navigation, the back-office live map and reseller map, and optional geocoding (GEO-04, COULD). Costs and quotas must be validated by HOCO (§11).

Decision (proposed).

• Delegate app. Google Maps Platform through the Maps SDK for Android/iOS (google_maps_flutter).
• Back-office. The Maps JavaScript API.
• Navigation. Handed to the Google Maps or Waze app through an intent: no in-app routing in V1.
• Geocoding. The Geocoding API, only on demand (address to position on back-office forms).
• Server. Distances, check-in tolerance and the recommended visit order use haversine — no routing API in V1.
• Keys. Per environment and platform, restricted by app signature or HTTP referrer; GOOGLE_MAPS_API_KEY stays server-side for geocoding.

Alternatives considered.

• Mapbox — good SDKs and styling, per-active-user pricing, thinner address and POI data in Algeria.
• OpenStreetMap-based stack — free data, but tile hosting and geocoding quality are on us.
• HERE — less used in the Flutter ecosystem.

Consequences.

• The best coverage and the app delegates already know.
• HOCO's billing account and quota monitoring are required.
• hoco_maps isolates the SDK, so choosing Mapbox later changes one package and the back-office map component.

Status. Proposed — pending decision D-14.

ADR-016 — GPS check-in tolerance and location sampling only during tours (privacy by design)Copy Anchor Link

Context. « La position est utilisée uniquement selon les règles validées par le client » and arrival « peut être soumise à une distance maximale » (cahier §6.3); tolerance, frequency, consent and retention are « à valider » (§8); consent and transparency are required (§10, SEC-07). Law 18-07 applies to delegates' location data; battery life on mid-range Android matters (NFR-04).

Decision (defaults, all tunable in settings):

• Check-in. Tolerance 150 m with a reported accuracy of at most 100 m. The app checks locally for immediate feedback; the server recomputes and stores the distance.
• Sampling. Only while a tour is IN_PROGRESS, every 5 minutes or 200 m; it stops when the tour is SUSPENDED or COMPLETED. The server drops any ping recorded outside an in-progress window.
• Retention. Positions are kept 90 days, then purged by a daily job.
• Consent and transparency. Consent before the first sampling (DA-04), transparency settings (DA-26), and an Android foreground-service notification while sampling.
• Access. Trails are visible only with field.view.
• End of day (proposal). Tours still open at 21:00 are suspended automatically, so sampling never runs overnight.
• Rule changes. A fact recorded offline is judged by the rules in force when it was recorded (occurredAt), never by a setting published afterwards (offline sync design).

Alternatives considered.

• Continuous background tracking during working hours — privacy, battery and legal exposure.
• No tracking — makes live follow-up (FLD-13) impossible.
• Geofence events per stop only — no kilometres and a poorer live view.

Consequences.

• A defensible privacy position with a clear technical guarantee: no position stored outside a tour.
• Kilometres and the live map are approximations at 5-minute sampling.
• The tolerance must be validated in the field, where dense centres and indoor shops degrade GPS (MOB-13), and every value must be validated by HOCO (cahier §15, « Décisions restantes à valider »).

Status. Accepted as defaults; values pending HOCO's validation (D-06, D-07, D-24, retention D-11).