Architecture العربية

🌐 English · العربية → · Bilingual index

🧭 Qwizin Architecture — Navigator

Central navigation hub. Every document, every feature, every identifier, every open question — with a route to each.

Date: 2026-07-20 · Status: Draft v0.1 · Documents: 19


Document Map#

flowchart TB
    NAV["🧭 <b>NAVIGATOR.md</b><br/><i>you are here</i>"]
    RM["📖 <b>README.md</b><br/>Overview · blockers ·<br/>baseline decisions"]

    subgraph FOUND["① Foundation — start here"]
        REQ["📋 <b>00-requirements-baseline</b><br/>Actors · modules · constraints<br/>5 contradictions · 25 open questions"]
        QAS["🎯 <b>01-quality-attribute-scenarios</b><br/>21 measurable scenarios"]
    end

    subgraph ARCH["② Architecture"]
        C4["🏛️ <b>arc42/03-context-and-containers</b><br/>C4 L1 + L2 · why not microservices"]
        BB["🧱 <b>arc42/05-building-block-view</b><br/>C4 L3 · modules · contracts ·<br/>events · <b>CI enforcement</b>"]
        RV["🔀 <b>arc42/06-runtime-view</b><br/>6 critical flows<br/><i>auth · docs · booking · certs ·<br/>search · tenancy</i>"]
        FB["⚙️ <b>arc42/06b-feature-flows-core</b><br/>F-01…F-09 + Level-0 pipeline map"]
        FC["💰 <b>arc42/06c-feature-flows-commerce-admin</b><br/>C-01…C-09"]
        DV["🚀 <b>arc42/07-deployment-view</b><br/>Regions · node pools · DR · capacity"]
        CC["🧩 <b>arc42/08-crosscutting-concepts</b><br/>Bilingual · errors · money · time ·<br/>idempotency · testing · retention"]
    end

    subgraph RISK["③ Risk & Ops"]
        RSK["⚠️ <b>arc42/11-risks-and-technical-debt</b><br/>16 ranked risks · 4 blockers"]
        DO["🐳 <b>deep-dives/devops-containerization-orchestration</b><br/>Containers · K8s · LB · autoscaling ·<br/>CI/CD · hardening"]
        SEC["🔐 <b>deep-dives/security-architecture</b><br/>Trust boundaries · tenancy · uploads ·<br/>integrity · STRIDE"]
    end

    subgraph ADR["④ Decisions"]
        A1["📐 <b>ADR-0001</b> Hosting"]
        A2["📐 <b>ADR-0002</b> Modular monolith"]
        A3["📐 <b>ADR-0003</b> Kubernetes"]
        A5["📐 <b>ADR-0005</b> Video port"]
        A7["📐 <b>ADR-0007</b> Multi-tenancy"]
    end

    NAV --> RM
    RM --> FOUND
    REQ --> QAS
    QAS --> ARCH
    REQ -.->|"traces to"| ARCH
    C4 --> BB --> RV --> FB --> FC
    C4 --> DV
    ARCH --> CC
    ARCH --> RISK
    QAS -.->|"drives"| RSK
    RISK --> ADR
    C4 -.-> A1
    BB -.-> A2
    DV -.-> A3
    RV -.-> A5
    SEC -.-> A7

    style NAV fill:#1168bd,stroke:#0b4884,color:#fff
    style REQ fill:#e8f0fe,stroke:#1168bd
    style RSK fill:#fde8e8,stroke:#c94a4a

🚦 Where to Start — by Role#

You are… Read, in this order
Tech Lead (Amir Haroun) READMERisksRequirements → everything
Business sponsor / Qwizin management README §Blockers → Requirements §5 ContradictionsOpen Questions below
Delivery vendor / dev lead RequirementsBuilding BlocksFeature FlowsDevOps
Backend developer Building BlocksFeature Flows core + commerceCross-cutting
DevOps / platform engineer DevOps deep-diveDeployment ViewADR-0001 + ADR-0003
Security reviewer Security architectureQA Scenarios §1–2Runtime View Flows 1,2,4,6 → ADR-0007
Legal / compliance counsel Security §11Risks §Category AADR-0001 §PDPLC-00 money topology
QA engineer QA ScenariosCross-cutting §8.7 — four system-specific test layers

🔍 Find It Fast — by Question#

"Where do I find…" Document
…what the platform actually does? 00-requirements-baseline §3
…the contradictions in the source PDFs? 00-requirements-baseline §5
how data flows for feature X? Feature index below
…the system-wide data pipeline map? 06b §Level 0
…security flows / trust boundaries? Security §1 + 06 Flows 1, 2, 6
…the module structure and boundaries? 05-building-block-view
how boundaries are enforced in CI? 05 §5.6 — Deptrac, arch tests, schema test
…the inter-module event catalogue? 05 §5.5
…why we're not doing microservices? ADR-0002
…the Kubernetes design? DevOps §2 + ADR-0003
…load balancing? DevOps §3 — three independent paths
…autoscaling signals? DevOps §4
…CI/CD pipeline? DevOps §6
…container hardening? DevOps §5, §9
…regions, node pools, DR? 07-deployment-view
…how tenant isolation works? ADR-0007 + 06 Flow 6
…Arabic / bilingual handling? 08 §8.1
…money, time, ID conventions? 08 §8.4
…the testing strategy? 08 §8.7
…data retention & deletion? 08 §8.8
…the payment / money topology? 06c C-00
…the STRIDE threat model? Security §9
…why hosting is Oracle KSA? ADR-0001
…the video platform decision? ADR-0005
…what could kill this project? 11-risks §Executive Summary
…what I need to decide? Open Questions below

🗂 Feature → Flow Index#

Complete coverage of SRC-BRD §7.1. This is the map from your BRD to the data flows.

User Management & Verification#

Feature Flow Document
Individual / Company / Consultant / Provider registration F-01 06b
Google Sign-In · Email · Phone · OTP Flow 1 06
Token lifecycle · refresh · revocation Flow 1 06
Profile management (incl. Employee "Limited") F-02 06b
Employee account provisioning F-03 06b
Legal document upload · scan · review Flow 2 06
Approve / Reject / Resubmit · activation F-04 06b

Consultancy#

Feature Flow Document
Consultant directory · profiles · availability F-05 06b
Booking · payment hold · consultant approval Flow 3 06
Video consultation session Flow 3 06
On-site consultation (distinct flow) F-06 06b
Appointment state machine C-01 06c

Templates#

Feature Flow Document
Catalogue · categories · free download F-07 06b
Customized template request (paid, human fulfilment) F-08 06b

Training · Assessment · Certification#

Feature Flow Document
Content authoring · assignment · progress F-09 06b
MCQ delivery · auto-grading · attempt history Flow 4 06
Certificate generation · QR · verification Flow 4 06

Marketplace#

Feature Flow Document
Directory · search · filtering (Arabic) Flow 5 06
Featured listing purchase C-03 06c
Featured ranking effect C-04 06c

Payment#

Feature Flow Document
Money-flow topology (Model A vs B) C-00 06c
Consultation payment state machine C-01 06c
Provider subscription · renewal · dunning C-02 06c
Featured listing payment C-03 06c
Payouts (⚠ largest regulatory risk) C-05 06c

Administration#

Feature Flow Document
Multi-role admin · approval queues C-06 06c
Content & marketplace management C-07 06c
Payment monitoring · reports · dashboard C-08 06c
Notifications fan-out C-09 06c

🔖 Identifier Registry#

Every prefix used across the documentation, and where it is defined.

Prefix Meaning Defined in
SRC-* Source document (BRD, MOM, UFC, DECK, TRN, CNT) 00 §1
ACT-* Actor type (IND, CO, EMP, CON, SP, ADM) 00 §2
MOD-* Module / building block 00 §3
CONF-* Contradiction in source documents 00 §5
OQ-* Open question requiring a decision 00 §6 + below
SEAM-* Phase-2 extraction seam 00 §7
CON-* Constraint (normative) 00 §8
QAS-* Quality attribute scenario 01
R-* Risk 11
Flow N Critical runtime scenario 06
F-* Core feature flow 06b
C-* Commerce / admin flow 06c
ADR-* Architecture decision record adr/

❓ Open Questions Registry#

25 open questions. Sorted by blocking status. ⛔ = blocks engineering.

⛔ Blockers — need a decision before build#

ID Question Owner Flow
OQ-10 Does Qwizin hold & disburse funds? SAMA licensing? Legal counsel C-00
OQ-11 ZATCA e-invoicing applicability (+ scaling constraint) Tax advisor Risks R-02
OQ-06 Corrected roles & permissions matrix (CONF-03) Sponsor / BA C-06
OQ-08 Are consultations recorded? (swings video cost ~80%) Sponsor ADR-0005
OQ-01 ⛔ Payment gateway — must support mada + auth/capture/void + payouts Architect C-00
OQ-04 ⛔ Training scope ruling (CONF-01 — BRD vs Training deck) Sponsor F-09
OQ-05 ⛔ Refund policy + consultant response SLA (CONF-02) Sponsor C-01

🟠 High — blocks a specific module#

ID Question Flow
OQ-02 Exact legal-document set per account type F-01
OQ-03 Consultant availability model (recurring / slots / negotiate) F-05
OQ-07 Company suspension cascade → employees, attempts, certificates F-03
OQ-09 Do certificates need third-party verifiability? Flow 4
OQ-12 Bilingual scope — dual Arabic/English, or Arabic-primary? Flow 5
OQ-18 On-site pricing — quoted per request or fixed rate? F-06
OQ-19 Who bears cost of a disputed on-site visit? F-06
OQ-21 Featured placement — unlimited or scarce? C-03
OQ-23 Commission model — flat %, tiered, per-category? C-05
OQ-24 Settlement frequency C-05
OQ-25 Who absorbs gateway fees? C-01
OQ-14 Revisions included in a customized template request? F-08
OQ-15 Delivery SLA for customized requests F-08

🟡 Medium#

ID Question Flow
OQ-13 Company → branch hierarchy needed? F-09
OQ-16 Fulfilment capacity limit / intake throttle F-08
OQ-17 Do consultant pricing/visibility edits re-enter review? F-02
OQ-20 Subscription grace period before delisting C-02
OQ-22 Does lowering a passing score retroactively pass attempts? C-07

⚠️ Risk Quick Reference#

ID Risk Severity Detail
R-01 SAMA licensing 🔴 Critical 11 §A
R-05 Cross-tenant data leak 🔴 Critical 11 §B
R-02 ZATCA scope + serialisation constraint 🔴 High 11 §A
R-03 PDPL operational duties unverified 🟠 High 11 §A
R-04 Recordings as sensitive health data 🟠 High 11 §A
R-06 Assessment / certificate integrity 🟠 High 11 §B
R-07 Malicious upload 🟠 High 11 §B
R-08 Module boundary erosion 🟠 High 11 §C
R-09 K8s operational burden vs team size 🟠 High 11 §C
R-10 Video cost / recording decision 🟠 High ADR-0005
R-11 Arabic search quality (one-way door) 🟠 High 11 §C
R-12R-16 Arabic PDF · no Laravel LTS · gateway · gaps 🟡 Medium 11

📊 Documentation Status#

Document Status
NAVIGATOR · README ✅ Complete
00-requirements-baseline ✅ Complete
01-quality-attribute-scenarios ✅ Complete
arc42/03-context-and-containers ✅ Complete
arc42/05-building-block-view ✅ Complete
arc42/06-runtime-view ✅ Complete
arc42/06b-feature-flows-core ✅ Complete
arc42/06c-feature-flows-commerce-admin ✅ Complete
arc42/07-deployment-view ✅ Complete
arc42/08-crosscutting-concepts ✅ Complete
arc42/11-risks-and-technical-debt ✅ Complete
deep-dives/devops-containerization-orchestration ✅ Complete
deep-dives/security-architecture ✅ Complete
ADR-0001 hosting ✅ Proposed — 4 verification items
ADR-0002 modular monolith ✅ Accepted
ADR-0003 Kubernetes ✅ Accepted — with recorded reservation
ADR-0005 video port ✅ Proposed — conditional
ADR-0007 multi-tenancy ✅ Accepted
ADR-0004 payment port Blocked on OQ-10 — writing it now would be speculation
ADR-0006 search engine Blocked on the Arabic bake-off spike — a one-way door needing measurement, not opinion
deep-dives/capacity-cost-model Blocked on OQ-08 + provider quotes
arc42/09 architecture decisions index ⬜ Superseded by this table + adr/
arc42/10 quality requirements ⬜ Superseded by 01

The three ⛔ items are deliberately not written. ADR-0004 depends on a legal answer that changes the payment topology; ADR-0006 depends on measured Arabic recall, not judgement; the cost model depends on the recording decision and quotes that don't exist yet. Writing them now would produce decisions with no evidence behind them — which is worse than an acknowledged gap.


🎯 Next Actions#

Decisions needed from you / the sponsor — the 7 ⛔ items above.

Spikes that retire disproportionate risk:

  1. Arabic search bake-off — 2–3 days, one-way door
  2. Arabic PDF render — 1 day, show it to an Arabic speaker
  3. Verify OCI region service matrix + CST class — hours, gates ADR-0001

Build before the second module exists: 4. Enforcement harness — Deptrac + arch tests + two-tenant adversarial suite 5. Transactional outbox + EventBus interface 6. RLS policies alongside the first tenant-scoped migration

Tech Lead · Amir Haroun Draft v0.1 · research & design only