arc42 §3 — Context, Scope & Container View

graph TB
    subgraph Actors["Human Actors"]
        IND["👤 Individual<br/><i>ACT-IND</i><br/>Browses, books, learns"]
        CO["🏢 Company Admin<br/><i>ACT-CO</i><br/>Manages employees, buys services"]
        EMP["👷 Employee<br/><i>ACT-EMP</i><br/>Learns, takes assessments"]
        CON["🎓 Consultant<br/><i>ACT-CON</i><br/>Sets availability, consults"]
        SP["🚚 Service Provider<br/><i>ACT-SP</i><br/>Maintains listing, subscribes"]
        ADM["🛡️ Platform Admin<br/><i>ACT-ADM</i><br/>Approves, moderates, reports"]
    end

    QW["<b>Qwizin Platform</b><br/><br/>Operational enablement platform for<br/>KSA restaurant &amp; hospitality sector.<br/>Consultancy · Templates · Training ·<br/>Assessment · Certification · Marketplace"]

    subgraph External["External Systems"]
        PAY["💳 Payment Gateway<br/><i>UNDECIDED — OQ-01</i><br/>mada, cards, holds, refunds, payouts"]
        VID["🎥 Video Provider<br/><i>Behind port — SEAM-02</i><br/>Real-time consultation media"]
        GOOG["🔑 Google Identity<br/>Sign-In (OIDC)"]
        SMS["📱 SMS Provider<br/>OTP + reminders (KSA)"]
        MAIL["✉️ Email Provider<br/>Transactional mail"]
        PUSH["🔔 Push Service<br/>APNs / FCM"]
        ZATCA["🧾 ZATCA / FATOORA<br/><i>Applicability — OQ-11</i><br/>E-invoicing clearance"]
    end

    IND & CO & EMP & CON & SP --> QW
    ADM --> QW

    QW -->|"Charge, refund, pay out"| PAY
    QW -->|"Create room, issue token,<br/>receive events"| VID
    QW -->|"Verify ID token"| GOOG
    QW -->|"Send OTP / reminder"| SMS
    QW -->|"Send transactional mail"| MAIL
    QW -->|"Deliver push"| PUSH
    QW -.->|"Submit / clear invoice"| ZATCA

    style QW fill:#1168bd,stroke:#0b4884,color:#fff
    style PAY fill:#c94a4a,stroke:#8b2f2f,color:#fff
    style ZATCA fill:#c94a4a,stroke:#8b2f2f,color:#fff
    style VID fill:#d98c1f,stroke:#96610f,color:#fff

graph TB
    subgraph Clients["Client Tier"]
        MOB["📱 Mobile App<br/><i>iOS / Android</i><br/>Primary client"]
        WEB["🌐 Web App<br/><i>Phase 1.5</i>"]
        ADMUI["🖥️ Admin Portal<br/><i>Server-rendered</i>"]
    end

    subgraph Edge["Edge — KSA Region"]
        CDN["CDN<br/>Static assets, template files"]
        WAF["WAF + DDoS"]
        ING["Ingress Controller<br/>TLS termination, routing,<br/>rate limiting"]
    end

    subgraph K8S["Kubernetes Cluster — In-Kingdom"]
        subgraph AppTier["Application Tier — stateless, HPA on RPS/latency"]
            API["<b>Qwizin API</b><br/><i>Laravel 13 · PHP 8.4</i><br/>Modular monolith<br/>MOD-IAM · ONB · CONS · TPL ·<br/>LRN · ASMT · CERT · MKT · PAY · ADM"]
        end

        subgraph WorkerTier["Worker Tier — HPA on queue depth"]
            WRK["<b>Queue Workers</b><br/><i>Same image, different entrypoint</i><br/>Notifications, webhooks,<br/>search indexing, reconciliation"]
            SCHED["<b>Scheduler</b><br/><i>Singleton</i><br/>Reminders, expiry, subscription<br/>renewal, predictive video scaling"]
        end

        subgraph Sidecars["Extracted Sidecars — distinct runtime or scaling profile"]
            PDF["<b>Document Renderer</b><br/><i>Headless browser runtime</i><br/>Certificates, custom docs<br/><b>Why separate:</b> heavy memory,<br/>different runtime, burst scaling"]
            SCAN["<b>Malware Scanner</b><br/><i>ClamAV</i><br/><b>Why separate:</b> large signature<br/>DB, isolation of untrusted input"]
            SRCH["<b>Search Engine</b><br/><i>Arabic-capable — TBD</i><br/><b>Why separate:</b> stateful,<br/>own memory/disk profile"]
        end

        subgraph VideoTier["Video Tier — conditional, see ADR-0005"]
            SFU["<b>Media Servers</b><br/><i>Only if self-hosted</i><br/>hostNetwork · session-based scaling"]
            TURN["<b>TURN/STUN</b><br/><i>Only if self-hosted</i>"]
        end
    end

    subgraph Data["Data Tier — In-Kingdom"]
        DB[("<b>PostgreSQL</b><br/>Primary + read replica<br/>Tenant-scoped")]
        REDIS[("<b>Redis</b><br/>Cache · queues · locks<br/>· rate limiting")]
        OBJ[("<b>Object Storage</b><br/>S3-compatible<br/>Legal docs · templates ·<br/>certificates<br/><i>Encrypted at rest</i>")]
    end

    subgraph Obs["Observability"]
        OTEL["OpenTelemetry Collector"]
        LOGS["Logs · Metrics · Traces<br/>Correlation-ID threaded"]
    end

    MOB & WEB --> CDN
    MOB & WEB & ADMUI --> WAF --> ING
    ING --> API
    ING -.->|"Deferred: BFF only if<br/>client divergence demands it"| API

    API --> DB
    API --> REDIS
    API --> OBJ
    API --> SRCH
    WRK --> DB & REDIS & OBJ & SRCH
    SCHED --> REDIS
    WRK --> PDF
    WRK --> SCAN
    API -.->|"signed URL"| OBJ
    MOB -.->|"direct download<br/>via signed URL"| OBJ

    API -->|"port"| VIDEXT["Video Provider<br/><i>managed or self-hosted</i>"]
    MOB -.->|"WebRTC media<br/><b>bypasses API</b>"| SFU
    SFU --- TURN

    API & WRK & PDF --> OTEL --> LOGS

    style API fill:#1168bd,stroke:#0b4884,color:#fff
    style PDF fill:#2d8659,stroke:#1c5638,color:#fff
    style SCAN fill:#2d8659,stroke:#1c5638,color:#fff
    style SRCH fill:#2d8659,stroke:#1c5638,color:#fff
    style SFU fill:#d98c1f,stroke:#96610f,color:#fff
    style TURN fill:#d98c1f,stroke:#96610f,color:#fff