Overview
What the HOCO B2B ecosystem is, who builds what, where everything lives and how to read these docs.
HOCO distributes phone accessories — HOCO, ACEFAST and BOROFONE — to shops across Algeria. Today the network runs on phone calls, WhatsApp and spreadsheets: resellers order by message, delegates report their day verbally, stock and payments are reconciled by hand. The project replaces that with one platform and one source of truth (cahier §1).
These docs are the team's working surface for that project: what we build and why (PRD), exactly how it must behave (SRS), how the apps talk to the server (API reference), what every screen does (design), how we work, and who delivers what, when (the plan).
The ecosystem
| Deliverable | For | Built by | Stack | Repository |
|---|---|---|---|---|
Central API (@hoco/server) | Every app | Anis | Express 5, oRPC contract-first REST + OpenAPI 3.1, Prisma 7, PostgreSQL, Redis/BullMQ, Better Auth | AnisBetehi/hoco |
Back-office (@hoco/dashboard) | HOCO staff — 6 internal roles | Anis | Next.js 16, Tailwind 4, TanStack Query/Table | AnisBetehi/hoco |
Reseller web (@hoco/web) | Resellers on a computer | Anis | Next.js 16 — same API, same account, same cart as the app | AnisBetehi/hoco |
| Reseller app | Shop owners | Imad | Flutter (Android first) | hoco-mobile (Imad's account) |
| Delegate app | Field sales delegates | Imad | Flutter, offline-first | hoco-mobile |
| Design of all of the above | Everyone | Akram | Claude Design — design system first | Claude Design project |
These docs (@hoco/docs) | The team and HOCO | Anis | Fumadocs, deployed later on the VPS | AnisBetehi/hoco |
The team
| Person | Role | Owns | Start here |
|---|---|---|---|
| Anis | Full-stack developer | Server, back-office, reseller web, docs, DevOps, the client relationship | Anis's tasks |
| Imad | Mobile developer (Flutter) | Reseller app and delegate app | Imad's tasks · Mobile guide |
| Akram | UI/UX designer | Design system, every interface, design QA, training and store assets | Akram's tasks · Design plan |
How the work is sequenced
V1 takes three months from design to deployment: from 18 October 2026 to mid-January 2027. Production go-live is at the start of January, followed by a two-week pilot; generalisation and V2 come after. Right now the team writes and validates these docs. No application code is written until they are done.
Three tracks start on day one and meet at the API contract and the designs:
- Anis defines the server's services, then the database, then every API endpoint with its request and response — published as an OpenAPI document with a mock server — so the mobile work is never blocked on server code (SRV-01 → SRV-02 → SRV-03).
- Imad builds the Flutter foundations that need no API (repository, core HTTP layer, localisation, the design system as soon as Akram's components exist), then generates the API client from the contract and builds against the mock server.
- Akram designs for 21 working days: the design system first (days 1–4), the screen inventory validated with the developers (day 5), then the reseller app, the delegate app, the back-office and the reseller web, and the handoff (day 21).
119 open tasks · 173.75 d of planned effort (434.25 d from scratch) · plan ends 22 Feb 2027
| Phase | Effort | Start | End |
|---|---|---|---|
| P0 — Foundations (cadrage, UX/UI, architecture & contract) | 36.25 d | 18 Oct 2026 | 16 Nov 2026 |
| P1 — V1 build & integration | 73 d | 08 Nov 2026 | 27 Dec 2026 |
| P2 — Acceptance, go-live & pilot | 27.5 d | 23 Dec 2026 | 14 Jan 2027 |
| P3 — Generalisation (after the 3 months) | 10.5 d | 14 Jan 2027 | 24 Jan 2027 |
| P4 — V2 evolutions | 26.5 d | 21 Jan 2027 | 22 Feb 2027 |
3-month frame: design → development → deployment — deadline 17 Jan 2027.
| Date | Milestone | Target | Reached when these tasks end |
|---|---|---|---|
| 18 Oct 2026 | Cadrage validated — validation sheet signed | — | PRJ-03 |
| 18 Oct 2026 | API contract v1 published (OpenAPI + mock server) | — | SRV-03 |
| 19 Oct 2026 | Server V1 feature-complete | — | SRV-26, SRV-40 |
| 21 Oct 2026 | Design system v1 ready (tokens + components) | — | DES-04 |
| 22 Oct 2026 | Screen inventory frozen | — | DES-05 |
| 29 Oct 2026 | Reseller app designs ready for client review | — | DES-10 |
| 05 Nov 2026 | Delegate app designs ready for client review | — | DES-14 |
| 08 Nov 2026 | Mobile foundations ready | — | MOB-11 |
| 12 Nov 2026 | Back-office designs ready for client review | — | DES-19 |
| 16 Nov 2026 | Design handoff complete | — | DES-21 |
| 03 Dec 2026 | Back-office and reseller web V1 feature-complete | — | DSH-12, WEB-05, WEB-06 |
| 15 Dec 2026 | Mobile apps V1 feature-complete | — | MDA-12 |
| 22 Dec 2026 | Staging integration complete | — | MOB-14, SRV-28 |
| 28 Dec 2026 | Acceptance report (PV de recette) signed | — | QA-02 |
| 29 Dec 2026 | Production go-live | on time — 17 Jan 2027 | LCH-01 |
| 30 Dec 2026 | Pilot starts | on time — 17 Jan 2027 | LCH-02 |
| 14 Jan 2027 | Pilot go / no-go | — | LCH-03, LCH-03B |
| 21 Jan 2027 | Generalisation complete | — | LCH-05 |
| 22 Feb 2027 | V2 delivered | — | SRV-38, DSH-21, MDA-20, WEB-20, DQA-12 |
The timeline shows every task on the calendar; progress shows what is actually done.
Decisions that shape everything
| Decision | Why | Where |
|---|---|---|
| REST + OpenAPI, contract-first with oRPC — not tRPC | The mobile apps are Flutter; Dart generates its client from OpenAPI while the Next apps keep end-to-end types | Architecture › ADR-002 |
| One central API; the Next apps hold no business logic | One set of rules for four clients | ADR-003 |
| Offline-first delegate app with idempotent replay | Field networks are weak; nothing may be lost or duplicated (cahier §7.3) | Offline sync design |
| Money in integer centimes, dates in UTC, business days in Africa/Algiers | No rounding drift, no day-boundary bugs | ADR-011 |
| French first, Arabic and English prepared | Cahier §9 | ADR-014 |
| V1 = the cahier's recommended scope (§14.1) plus after-sales (SAV) and returns; loyalty, packs, detailed credit and integrations in V2 | Ship the field-to-order loop first, with a clean way to handle problems after delivery | Scope |
Product rules decided by the team (17 Oct 2026)
These complete the cahier and apply to every app:
| Rule | Consequence |
|---|---|
| Three prices per product — super-gros, demi-gros, détail | Each reseller declares their customer type at sign-up (confirmed at validation) and sees only that price (PRC-02, AUTH-11) |
| Guest browsing without prices | Anyone can open the reseller app or web and browse; prices appear after sign-up (AUTH-10) |
| Availability, never quantities | Resellers and guests see En stock / En rupture only; quantities live in the back-office (STK-07) |
| Every order is confirmed by a person | No automatic confirmation — the back-office works an "orders to confirm" queue (ORD-14) |
| Live order status | Reseller screens update in real time and every status change is notified (ORD-15) |
| Advanced filters | Price range, category and sub-category, brand, product attributes, availability, promotion — on web and mobile (CAT-12) |
| Regional WhatsApp support | A fixed WhatsApp button opens the support number of the user's region (SUP-05) |
| After-sales service and returns in V1 | Claims on delivered orders handled in the back-office; cancellations and returns put quantities back in stock automatically (SUP-04, ORD-13) |
Reading guide
I'm Anis
Services → database → API contract, then server modules, back-office and reseller web. Start with the service catalogue and the database design.
I'm Imad
The Flutter repository, architecture, API integration and offline sync — then the API reference and the screen specs of both apps.
I'm Akram
The 21-day plan, the design-system brief, the client's reference screens and the screen inventory to validate on day 5.
I'm from HOCO
The PRD, the scope and the decisions we need from you to stay on schedule.
| Section | What it answers |
|---|---|
| Timeline · Progress · Team tasks | When, who, what is done |
| Ways of working | Repositories, branches, reviews, the API-contract loop, rituals, definition of done |
| PRD · User flows | What we build and why; every journey end to end |
| SRS | Requirements, lifecycles, business rules, permissions, notifications, acceptance scenarios, data model, API, integrations, operations, decisions |
| Architecture | Containers, deployment and the decision records |
| Design | Design plan, design system, reference screens, inventory and every screen's specification |
| Mobile | The Flutter side in depth |
| Planning method | How effort becomes dates |
Source
Everything traces back to the client's Cahier des charges — Écosystème B2B HOCO, version 1.0 (July 2026), section by section — see source traceability. Anything not described there is a change request (process).