arc42 §8 — Cross-Cutting Concepts

Status: Draft v0.1 · Date: 2026-07-20 Purpose: Patterns that apply across modules. Decided once here rather than inconsistently in twelve places.

8.1 Bilingual Content (Arabic / English)#

OQ-12 · QAS-LOC-01, QAS-PERF-02 · CON-12

Qwizin is a Saudi platform with an Arabic BRD. Arabic is not a localisation afterthought — it is the primary language of the market.

Storage: split by content type, not by field length#

The distinction is not field length — it is whether the translation has an independent lifecycle. A JSON blob cannot express "the Arabic version is approved and the English one isn't", and retrofitting that later means migrating your most valuable content.

Arabic normalisation — mandatory, not optional#

Users type أ / إ / آ / ا interchangeably, ى and ي interchangeably, and almost never type diacritics. Without folding, search recall collapses silently and totally — a user searches in Arabic, gets nothing, and concludes the directory is empty.

Normalisation pipeline (applied identically at index time and to queries):

strip tatweel (ـ) → strip diacritics/harakat → fold أإآٱ → ا
→ fold ة → ه → fold ى → ي → normalise Arabic-Indic digits ٠-٩ → 0-9

Own this in the application layer. It is roughly 150 lines of well-tested string handling, it delivers the higher-impact half of Arabic search quality on any engine, and it makes the engine choice reversible rather than a one-way door (R-11). This is the single most portable investment available.

Additional Arabic concerns#

API response shape#

Resolve server-side by default; return the resolved string plus metadata.

{ "id": 42, "name": "مطعم الرياض", "locale": "ar", "locale_fallback": false }

8.2 Error Handling & API Contract#

Error response shape#

Consistent across every endpoint. Mobile clients must be able to act on errors programmatically.

{
  "error": {
    "code": "account.not_approved",
    "message": "Your account is under review.",
    "message_ar": "حسابك قيد المراجعة.",
    "details": { "state": "under_review", "submitted_at": "..." },
    "correlation_id": "01J..."
  }
}

Status code discipline#

Failure philosophy#

8.3 Idempotency & Concurrency#

Idempotency#

Duplicate processing of a payment capture is a double charge. This is not a robustness nicety.

Concurrency#

8.4 Time, Money & Identifiers#

Time#

Money#

Identifiers#

8.5 Observability#

QAS-OPS-01 — a single on-call engineer must diagnose a 02:00 incident without tribal knowledge.

flowchart LR
    REQ["Request"] -->|"generate<br/>correlation_id"| API["API"]
    API -->|"propagate"| JOB["Queue job"]
    API -->|"propagate"| SIDE["Sidecar"]
    API -->|"propagate"| EXT["External call"]
    API & JOB & SIDE --> LOGS["Structured logs<br/><i>correlation_id on every line</i>"]
    API & JOB & SIDE --> TRACE["Traces"]
    API & JOB & SIDE --> METRIC["Metrics"]
    LOGS & TRACE & METRIC --> ALERT["Alerts on<br/><b>user-facing SLOs</b>"]

Business metrics are first-class, not an afterthought: the four SRC-MOM §13 KPIs require event capture designed in from the start. Reconstructing "templates downloaded" from access logs a year later is expensive and inaccurate.

8.6 Configuration & Feature Management#

Configuration hierarchy#

What must be database configuration, not code#

CON-07 and CON-08 are explicit constraints, and both are trivially satisfied if designed correctly from the start:

• Subscription plans and pricing (CON-07)
• Assessment passing scores (CON-08)
• Featured listing packages
• Required document sets per account type (pending OQ-02)
• Notification templates
• Consultant response SLA, booking expiry windows (pending OQ-05)

Changing a passing score must never require a release. Anything a business stakeholder will plausibly want to adjust belongs in the admin panel — hardcoding it converts a five-minute business decision into a deployment.

Feature flags#

For CONF-01-dependent training features, and for the gradual rollout of high-risk changes (RLS enforcement, search engine switch). Keep the flag set small and remove flags once decided — a permanent flag is untested branching.

8.7 Testing Strategy#

Ordered by defect-prevention value for this system, not by convention.

The four starred layers are unusual and specific to this system's risks. A conventional test pyramid would miss all four, and each guards a failure mode that is silent in production.

8.8 Data Retention & Deletion#

QAS-CMP-01 · ⚠️ Retention periods require legal confirmation (R-03)

The enumeration problem#

The hard part of a data-subject request is not deletion — it is finding everything. Once personal data has spread into a search index, a reporting projection, a log pipeline, and backups, "locate all data about this person" is unanswerable without a personal-data inventory maintained as a first-class artifact.

Build the inventory while the system is small. Retrofitting it means auditing every store after the fact.

8.9 Concept Summary#