Sur-MeZur — implementation

Full-stack implementation of the Sur-MeZur marketplace: bilingual (FR/EN) app connecting clients and tailors in Cameroon, with AI body measurement, 3D avatar try-on, negotiation/quoting, Mobile Money escrow payment, and pattern generation.

Built from Documentation/ (UI/UX spec, database schema, backend spec, technical process notes, feasibility studies, cahier des charges) and the Sur-MeZur.dc.html Claude Design prototype.

What this is

• backend/ — FastAPI + SQLAlchemy, implementing the full database schema and REST API from the spec docs, with real business logic: the commission tiers, the 70/30 escrow split, the 3-offer/7-day negotiation cap, quote-before-payment gating, pattern-after-deposit gating, chat restricted to modifications, RG-01 through RG-19 from the CDC.
• mobile/ — React Native (Expo SDK 54, Expo Router), the primary client: native client/tailor/admin apps implementing every screen from the UI/UX spec, using the design tokens (colors, fonts, radii) from the brand doc and icons from Lucide (per doc 1's "icônes linéaires (Lucide)" — no emoji anywhere in the UI). See mobile/README.md.
• frontend/ — React + TypeScript (Vite), the original mobile-first web build of the same app. Superseded by mobile/ as the primary deliverable once the user asked for a native Expo rewrite, but left in place — it still runs standalone and its src/ was the direct porting source for mobile/src/, so the two stay easy to compare screen-for-screen.

What's real vs. mocked (and why)

The full spec calls for infrastructure (PostgreSQL+PostGIS, Redis+Celery, S3+CDN, real MTN/Orange APIs, SMPLer-X/MakeHuman/Blender/Freesewing AI pipelines, a native mobile app) that isn't realistic to stand up in this environment. Every simplification below keeps the same data model / API contract as the spec, so it's a config change, not a rewrite, to go further:

Spec'd	Here	Why / how to upgrade
PostgreSQL + PostGIS	SQLite via DATABASE_URL; tailor proximity via Python haversine (app/services/geo.py)	Point DATABASE_URL at Postgres; PostGIS ST_DWithin is a drop-in optimization on top of the same lat/lng columns
Redis + Celery workers	FastAPI BackgroundTasks + a status column (processing→ready) polled by the client	Same async contract (create job → poll status) — swap the BackgroundTasks.add_task calls in api/v1/measurements.py, avatars.py, tryon.py, services/payment_provider.py for real Celery tasks
S3 + CDN	Local disk under backend/uploads/, served via FastAPI static files	Swap app/services/storage.py's save_upload for an S3 client; URLs are already opaque strings
Real SMS OTP	OTP code returned directly in /auth/otp/request's response (dev_code)	Wire app/services/otp.py to an SMS gateway
Real AI (SMPLer-X / MediaPipe / MakeHuman-MPFB / Freesewing)	Deterministic mock generators in app/services/mock_ai.py, behind the same endpoint contracts (POST /measurements/session/{id}/photos, POST /avatars, POST /tryon, GET /orders/{id}/pattern)	Replace the functions in mock_ai.py with calls to the real microservices from doc 3/4; nothing calling them needs to change
Mobile Money (MTN MoMo / Orange Money)	PaymentProvider abstract class + SandboxMomoProvider in app/services/payment_provider.py, simulating the initiate → webhook confirm round trip	Implement a new PaymentProvider subclass with real API/aggregator (CinetPay/Monetbil/Campay) credentials; POST /payments/webhook already has the right shape for a PSP callback
Native mobile app (React Native)	React web app (mobile-first, ~420px canvas)	No mobile toolchain/device available here; the screens/flows map 1:1 to the RN spec, so porting components to RN is mechanical

Everything else — every table in the DB spec, every REST endpoint in the backend spec, every business rule in the CDC (RG-01…RG-19), the commission table, the 70/30 split, the pattern-release gate, the modification-refusal rule (RG-18) — is implemented and exercised end-to-end by an automated smoke test (see below).

The 3D "avatar"/"try-on" viewer (frontend/src/components/Viewer3D.tsx) is a real interactive Three.js scene — drag to orbit, scroll to zoom — built procedurally from the client's actual measurement numbers and tinted by skin tone / fabric color. It is not a photorealistic MakeHuman mesh (no such pipeline runs here), but it is exactly the "reusable Viewer 3D component, placeholder if the tool has no 3D engine" the UI/UX spec asks for.

Running it

Backend (Python 3.10+):

cd backend
python -m venv venv
./venv/Scripts/activate        # venv\Scripts\activate on native Windows shells
pip install -r requirements.txt
python -m app.seed             # creates demo accounts + catalog data
python -m uvicorn app.main:app --reload --port 8000

Frontend (Node 18+):

cd frontend
npm install
npm run dev                    # http://localhost:5173, proxies /api to :8000

Open http://localhost:5173.

Accounts (created by app/seed.py)

Role	Phone	Password
Admin	+237696982953	fixé à l'installation : ADMIN_PASSWORD=... python -m app.seed (sinon généré et affiché une fois)

No demo tailor or client account is created — both register their own accounts from the app. app/seed.py still seeds ownerless catalog data (fabrics, accessories); garment models and ready-to-wear listings only appear once a real tailor registers and publishes them.

Automated verification

backend/app/main.py's API was exercised end-to-end with a smoke-test script driving the full order lifecycle through real HTTP calls: register/login → measurement session → mock-AI processing → avatar → try-on → order creation (client's first offer) → tailor's mandatory quote → commission-tier calculation → quote acceptance → 70% deposit → sandboxed MoMo confirmation → payment-split verification (70/30/40 math) → pattern release (gated on deposit) → a tailor-proposed modification refused by the client (verifying RG-18: no price change, no client penalty) → chat → delivery confirmation → escrow release → review → tailor rating recompute. All assertions passed.

The frontend builds cleanly under TypeScript strict mode (npm run build). Manual click-through in a browser wasn't possible in this session (no headless-browser tooling or network access to install one here) — please run both servers and click through yourself; only the admin account above is pre-seeded, register client/tailor accounts from the app to test those roles.

Project structure

See backend/app/ (models → schemas → services → api/v1) and frontend/src/ (theme → i18n → api → state → components → pages, split into auth/, client/, tailor/, admin/, shared/) — file layout mirrors the plan in the doc set closely enough that finding e.g. "where offers are created" or "where the try-on screen lives" should be a Ctrl+P away.