Architecture

System-level design. Reads .context/wiki/ as source-of-truth for what the app does; encodes how it does it.

Files

File	Purpose
overview.md	Subsystems, data flow, key invariants, service boundaries
flows.md	Five load-bearing sequence flows (publish, unlock, 30-day takedown, review queue, complaint/refund)
non-functional.md	Regulatory constraints, SLOs, observability, cost ceilings, open questions

Design principles (load-bearing)

1. Server-authoritative money. Wallet debits, unlock atomicity, refunds — all in apps/api. Web and mobile request an action; the server decides. Never trust a client-computed balance.
2. Visibility mask is a server-side projection. Locked vs unlocked property detail is the same record. apps/api strips masked fields based on the buyer's unlock ledger before responding. Frontend cannot un-mask.
3. State machine over booleans. Listing state (draft / in_review / needs_changes / live / expired / paused / sold / removed) is one enum with an explicit transition table. No parallel flags.
4. Everything reviewable is versioned. Publish, renew, and edit each create a new ListingVersion. The Listing points at its latest approved version. The reviewer sees the diff.
5. CATALOG is the single source of copy + prices. packages/copy is code-generated from .context/wiki/entities/catalog.md; UI never hard-codes strings or amounts. Drift is caught in CI.
6. Every admin/reviewer write emits an AuditEvent. No exceptions. This is how we survive a DPDP or NCDRC audit.
7. Cost < ₹5,000/month until 1000 active users. If a subsystem breaks this, we redesign the subsystem, not raise the ceiling.

Cross-references

• Product intent: ../product/spec.md, ../product/catalog.md
• Regulatory constraints: ../product/regulatory.md
• Tech stack decisions: ../tech-stack/ (to be written in step 4 — architecture here calls out which subsystem is needed; step 4 locks what each one is built with)
• Screens the architecture must serve: ../product/screens.md