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

Qwizin — Architecture Documentation

Status: Draft v0.1 · Date: 2026-07-20 · Tech Lead: Amir Haroun Scope: Research and design documentation only. No implementation has been started.

🧭 Open the NAVIGATOR →#

Document map · find-by-question index · feature → data-flow index · identifier registry · all 25 open questions · risk quick-reference · status board.

⛔ Read First — Four Blockers#

These must be resolved before engineering begins. Three require Saudi legal counsel, not further research.

Do not spend engineering effort on payments or invoicing until 1 and 2 are answered. They determine what gets built, not merely how.

Reading Order#

Start here#

The architecture#

| arc42/07-deployment-view.md | Regions, environments, node pools, data tier, network topology, disaster recovery (in-Kingdom, no cross-border), launch capacity sizing. | | arc42/08-crosscutting-concepts.md | Bilingual/Arabic handling, error contract, idempotency & concurrency, money/time/ID conventions, observability, configuration, testing strategy, retention & deletion. |

Deep dives#

Decision records#

ADR-0004 (payment port), ADR-0006 (search engine), and the capacity/cost model are deliberately unwritten. Each depends on evidence that does not yet exist — a legal ruling, a measured Arabic bake-off, and provider quotes respectively. Writing them now would produce decisions with nothing behind them.

Baseline Decisions#

Findings That Overturned Assumptions#

Recorded because acting on the original assumptions would have produced a worse system.

1. PDPL does not mandate in-Kingdom storage for private-sector personal data. Article 29 permits cross-border transfer under conditions (SCCs, BCRs, or accreditation, plus a risk assessment). In-Kingdom hosting remains correct — but because it eliminates the transfer-compliance workstream and pre-satisfies the CST government-data rule, not because it is legally forced. Sources conflict; counsel required.
2. AWS has no verifiable GA region in Saudi Arabia. AWS's own documentation lists only Bahrain and UAE in the Middle East, contradicting several secondary sources claiming a January 2026 launch.
3. LiveKit does not escape Kubernetes' hostNetwork constraint. Its own docs require host networking and one pod per node — architecturally identical to Jitsi's JVB. "LiveKit is the cloud-native one" is false as commonly stated.
4. Recording destroys Jitsi's cost advantage. Jibri joins as a third participant, which forces 1-to-1 calls out of P2P mode and back through the bridge — killing the ~80 % saving and adding the most expensive tier. Both effects flow from one product decision (OQ-08).
5. Meilisearch has no stemming and no query-time boosting, and its OSS build has no HA (replication and sharding are BSL-licensed Enterprise). Both matter directly for Arabic recall and for featured-listing monetisation.
6. Laravel has no LTS. The last was version 6 (2019). Laravel 12's bugfix window closes 2026-08-13. An annual major upgrade must be budgeted as routine work.
7. Gate::before returning false breaks every policy in the application — the intuitive way to implement "account must be approved" is a documented footgun that also disables super-admin review.

Source Documents#

The twelve files in the parent directory. Note that six of them — the SOP, HACCP, food-safety, and audit workbooks — are content specimens for the template library, not system specifications. Their structure matters for one reason: the audit workbooks are row-per-control checklists, signalling that "downloadable template" is a transitional form of what becomes an interactive digital audit instrument (SEAM-03).

Research Provenance & Limits#

This documentation is backed by parallel research across KSA cloud/regulatory landscape, video infrastructure, Laravel architecture patterns, and security/compliance.

Two honest limitations:

1. The session's web-search budget was exhausted, and several research strands terminated early. Items that could not be verified against primary sources are explicitly marked UNVERIFIED throughout rather than filled in from memory. Cost figures and regulatory claims are precisely where a plausible-sounding wrong number does damage — none appear here unless retrieved or labelled as structural inference.
2. Nothing here is a legal opinion. The SAMA, ZATCA, and PDPL sections are scoping frameworks and question lists for counsel, not answers.

Principal open verification items are listed in arc42/11-risks-and-technical-debt.md R-16.

Recommended Next Steps#

Before any code:

1. Engage Saudi counsel on SAMA, ZATCA, and PDPL operational duties
2. Obtain the corrected roles & permissions matrix (CONF-03)
3. Rule on OQ-08 (recording) and CONF-01 (training scope)

Cheap spikes that retire disproportionate risk: 4. Arabic search bake-off — 2–3 days, ~500 real listings, all four engines with a normalisation pipeline in front. One-way door. 5. Arabic PDF render — 1 day. Produce one real bilingual certificate and show it to an Arabic speaker. 6. Verify OCI region service matrix and CST registration class — hours, and gates ADR-0001

Build before the second module exists: 7. Enforcement harness — Deptrac (note: deptrac/deptrac, the old qossmic/deptrac is abandoned) + architecture tests + the two-tenant adversarial suite. Retrofitting boundaries onto six modules costs ~20× more. 8. Transactional outbox + EventBus interface — about a day, the cheapest extraction insurance available 9. RLS policies alongside the first tenant-scoped migration — adding RLS to a populated table needs a maintenance window

Deliberately not written yet — each blocked on evidence rather than effort: