🌐 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#
🔍 Find It Fast — by Question#
🗂 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-12–R-16 |
Arabic PDF · no Laravel LTS · gateway · gaps |
🟡 Medium |
11 |
📊 Documentation Status#
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:
- Arabic search bake-off — 2–3 days, one-way door
- Arabic PDF render — 1 day, show it to an Arabic speaker
- 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