arc42 §6 — Runtime View: Data Flows & Security Flows

sequenceDiagram
    autonumber
    participant M as 📱 Mobile Client
    participant ING as Ingress + WAF
    participant API as Qwizin API
    participant G as Google Identity
    participant SMS as SMS Provider
    participant R as Redis
    participant DB as PostgreSQL

    rect rgb(240,240,255)
    Note over M,DB: Registration — phone path
    M->>API: POST /v1/auth/register {phone, name, type}
    API->>API: Validate, rate-limit by IP + phone
    API->>R: Store OTP hash, TTL 5min, attempt counter
    API->>SMS: Send OTP
    Note over API,SMS: ⚠ Toll-fraud control: per-phone,<br/>per-IP, per-country quotas
    M->>API: POST /v1/auth/verify {phone, otp}
    API->>R: Verify hash + increment attempts
    Note over API,R: Lock after N attempts.<br/>Constant-time compare.
    API->>DB: Create user (state: pending_profile)
    API-->>M: {access_token 15m, refresh_token}
    end

    rect rgb(240,255,240)
    Note over M,DB: Registration — Google path
    M->>G: Native Sign-In → ID token
    M->>API: POST /v1/auth/google {id_token}
    API->>G: Fetch JWKS (cached)
    API->>API: ⚠ Verify signature, iss, aud, exp, nonce
    Note over API: NEVER trust client-supplied<br/>profile claims. Server verifies<br/>the token itself.
    API->>DB: Find or create by verified sub
    API-->>M: {access_token, refresh_token}
    end

    rect rgb(255,245,235)
    Note over M,DB: Refresh with reuse detection — QAS-SEC-04
    M->>API: POST /v1/auth/refresh {refresh_token}
    API->>DB: Look up token → family_id, used_at
    alt Token already consumed (replay / theft)
        API->>DB: 🚨 Revoke ENTIRE token family
        API->>API: Emit security event, notify user
        API-->>M: 401 — re-authentication required
    else Token valid
        API->>DB: Mark consumed, issue successor in same family
        API-->>M: {new access_token, new refresh_token}
    end
    end

sequenceDiagram
    autonumber
    participant U as 🏢 Company Admin
    participant API as Qwizin API
    participant OBJ as Object Storage
    participant Q as Queue
    participant SC as Malware Scanner
    participant ADM as 🛡️ Platform Admin
    participant DB as PostgreSQL

    rect rgb(255,240,240)
    Note over U,DB: 🔒 TRUST BOUNDARY — untrusted file enters
    U->>API: POST /v1/onboarding/documents (multipart)
    API->>API: AuthZ: is this user's own org?
    API->>API: Validate size, count, declared type
    API->>API: ⚠ Magic-byte inspection<br/>(NOT extension or client MIME)
    API->>OBJ: PUT → quarantine/ bucket
    Note over OBJ: Quarantine is a SEPARATE bucket.<br/>No read access from admin UI.<br/>Encrypted at rest.
    API->>DB: document(state: uploaded, version: n)
    API->>Q: dispatch ScanDocument
    API-->>U: 202 Accepted — "under review"
    Note over API,U: Async by design: user is not<br/>blocked on the scan (QAS-SEC-03)
    end

    Q->>SC: Scan object
    alt Malware detected
        SC-->>DB: state: rejected_malware
        Note over DB: Admin NEVER sees the file.<br/>Security event raised.
        DB->>U: Notify — resubmit required
    else Clean
        SC->>OBJ: Move quarantine/ → documents/
        SC->>DB: state: pending_review
        DB->>ADM: Enqueue in review queue
    end

    rect rgb(240,240,255)
    Note over ADM,DB: Admin review — QAS-SEC-02
    ADM->>API: GET /v1/admin/documents/{id}
    API->>API: AuthZ: admin role + review permission
    API->>OBJ: Generate signed URL, TTL ≤ 5 min
    API->>DB: 📝 Audit: admin X viewed doc Y at T
    API-->>ADM: {signed_url}
    ADM->>OBJ: GET via signed URL
    Note over ADM,OBJ: Direct fetch. Never proxied<br/>through app domain.<br/>Content-Disposition: attachment
    end

    rect rgb(240,255,240)
    Note over ADM,DB: Decision — QAS-CMP-02
    alt Approved
        ADM->>API: POST /v1/admin/documents/{id}/approve
        API->>DB: BEGIN TX
        API->>DB: document.state = approved
        API->>DB: 📝 Audit: actor, timestamp, prior→new, reason
        API->>DB: Re-evaluate org activation state
        API->>DB: COMMIT
        Note over DB: Org activates ONLY when ALL<br/>required docs approved (CON-04)
        DB->>U: Notify — account active
    else Rejected
        ADM->>API: POST .../reject {reason}
        API->>DB: state = rejected + reason + audit
        DB->>U: Notify with reason → resubmission allowed
        Note over DB: Resubmission creates version n+1.<br/>⚠ NEVER overwrites version n —<br/>the evidence behind the original<br/>decision must survive (QAS-CMP-02)
    end
    end

sequenceDiagram
    autonumber
    participant C as 👤 Customer
    participant API as Qwizin API
    participant PAY as 💳 Payment Gateway
    participant CON as 🎓 Consultant
    participant VID as 🎥 Video Provider
    participant SCH as Scheduler
    participant Q as Queue

    rect rgb(240,240,255)
    Note over C,PAY: Booking + payment AUTHORIZATION (not capture)
    C->>API: POST /v1/bookings {consultant, slot, type}
    API->>API: Validate slot free, check consultant active
    API->>API: 🔒 Pessimistic lock on slot
    API->>API: booking(state: pending_payment), slot held
    API-->>C: {booking_id, amount, idempotency_key}

    C->>API: POST /v1/bookings/{id}/pay {idempotency_key}
    API->>PAY: AUTHORIZE (hold) — not capture
    Note over API,PAY: ⚠ AUTHORIZE ONLY.<br/>Capture happens after the<br/>consultant accepts. This is the<br/>fix for CONF-02.
    PAY-->>API: {auth_id, status}
    API->>API: booking(state: awaiting_consultant)
    API->>CON: 🔔 Booking request — respond within SLA
    end

    rect rgb(255,245,235)
    Note over CON,PAY: Consultant decision — bounded by timer
    alt Consultant accepts within SLA
        CON->>API: POST /v1/bookings/{id}/accept
        API->>PAY: CAPTURE {auth_id}
        PAY-->>API: captured
        API->>API: booking(state: confirmed)
        API->>Q: Schedule reminders (T-24h, T-1h)
        API->>C: 🔔 Confirmed
    else Consultant rejects
        CON->>API: POST /v1/bookings/{id}/reject
        API->>PAY: VOID {auth_id}
        Note over API,PAY: Void, not refund — no funds<br/>ever moved. Cleaner for the<br/>customer and cheaper in fees.
        API->>API: booking(state: rejected), release slot
        API->>C: 🔔 Declined — no charge
    else SLA expires (no response)
        SCH->>API: Expire booking
        API->>PAY: VOID {auth_id}
        API->>API: booking(state: expired), release slot
        API->>C: 🔔 Expired — no charge
        Note over API: ⚠ Slot MUST be released.<br/>Consultant non-response must not<br/>silently consume inventory.
    end
    end

    rect rgb(240,255,240)
    Note over C,VID: Consultation — QAS-AVL-01
    SCH->>API: T-5min: provision session
    API->>VID: createRoom(booking_id) [via port]
    VID-->>API: {room_ref}
    C->>API: POST /v1/bookings/{id}/join
    API->>API: AuthZ: participant + within window
    API->>VID: issueToken(room, identity, role)
    API-->>C: {join_token, room_ref}
    C-->>VID: 🎥 WebRTC media — DIRECT, bypasses API
    Note over C,VID: Media never traverses the API tier.<br/>API controls session lifecycle only.
    VID->>API: webhook: participant_joined / left / ended
    API->>API: Record actual duration + outcome
    end

    rect rgb(255,240,240)
    Note over C,PAY: Failure path
    alt Session fails to establish
        API->>API: Detect: no participants joined in window
        API->>API: Flag for resolution
        API->>PAY: REFUND (policy-driven)
        Note over API,PAY: ⚠ Policy undefined in sources.<br/>Who bears a failed session?<br/>→ OQ-05
    end
    end

sequenceDiagram
    autonumber
    participant E as 👷 Employee
    participant API as Qwizin API
    participant DB as PostgreSQL
    participant Q as Queue
    participant PDF as Document Renderer
    participant OBJ as Object Storage
    participant V as 🔍 Public Verifier

    rect rgb(240,240,255)
    Note over E,DB: Delivery — QAS-INT-01
    E->>API: POST /v1/assessments/{id}/start
    API->>API: AuthZ: assigned + attempts remaining
    API->>DB: attempt(state: in_progress, started_at)
    API->>DB: Fetch questions
    API->>API: ⚠ STRIP all correctness indicators
    API-->>E: {questions, options} — NO answer key
    Note over API,E: 🚨 The correct answer NEVER<br/>reaches the client in any form:<br/>not a flag, not ordering, not<br/>a hash, not in metadata.<br/>Contract-tested in CI.
    end

    rect rgb(240,255,240)
    Note over E,DB: Submission & server-side grading — QAS-INT-02
    E->>API: POST /v1/assessments/{id}/submit {answers}
    API->>API: Validate attempt open + not expired
    API->>DB: BEGIN TX
    API->>DB: Load answer key (server-side only)
    API->>API: 🧮 Grade — score computed here, never received
    API->>DB: Load passing_score (admin-configurable, CON-08)
    API->>DB: attempt(answers, score, passed) — APPEND-ONLY
    Note over DB: Every attempt persisted immutably.<br/>Client-submitted scores are<br/>never trusted or even accepted.
    alt Passed
        API->>DB: certificate(state: pending, attempt_id) 🔗
        Note over DB: Certificate transactionally bound<br/>to a specific graded attempt
        API->>Q: dispatch GenerateCertificate
    end
    API->>DB: COMMIT
    API-->>E: {score, passed} — result never lost even if<br/>PDF generation later fails (QAS-AVL-04)
    end

    rect rgb(255,245,235)
    Note over Q,OBJ: Async generation — QAS-SCL-03, QAS-LOC-01
    Q->>PDF: Render {holder, competency, date, cert_id, QR}
    Note over PDF: ⚠ Arabic: contextual glyph joining,<br/>bidi layout, embedded fonts.<br/>Golden-image tested.
    PDF->>PDF: Embed QR → verification URL
    PDF->>PDF: Apply cryptographic signature
    PDF->>OBJ: Store immutably
    PDF->>DB: certificate(state: issued, hash)
    DB->>E: 🔔 Certificate ready
    end

    rect rgb(240,240,255)
    Note over V,DB: Third-party verification — QAS-INT-03
    V->>API: GET /verify/{cert_id} (public, unauthenticated)
    API->>DB: Look up by unguessable ID
    API->>API: Evaluate CURRENT validity:<br/>revoked? company suspended? expired?
    API-->>V: {holder, competency, issued, status}
    Note over API,V: Minimal disclosure — enough to<br/>verify, not enough to enumerate<br/>or harvest personal data.<br/>Rate-limited.
    end

sequenceDiagram
    autonumber
    participant U as 👤 User
    participant API as Qwizin API
    participant SRCH as Search Engine
    participant DB as PostgreSQL
    participant Q as Queue

    rect rgb(240,255,240)
    Note over DB,SRCH: Indexing pipeline — async
    DB->>Q: Provider created / updated / subscription changed
    Q->>Q: ⚠ Debounce: subscription state changes<br/>are frequent and bursty
    Q->>SRCH: Upsert document
    Note over SRCH: Indexed: name, description,<br/>categories, city, ar+en variants,<br/>subscription_tier, is_featured
    end

    rect rgb(240,240,255)
    Note over U,SRCH: Query — QAS-PERF-02
    U->>API: GET /v1/marketplace?q=مورد أغذية&city=..&cat=..
    API->>API: Normalise Arabic:<br/>أإآ→ا · ة→ه · ى→ي · strip diacritics · strip tatweel
    API->>SRCH: Query with filters + featured boost
    SRCH->>SRCH: Relevance score
    SRCH->>SRCH: Apply featured multiplier
    Note over SRCH: ⚠ Boost is a MULTIPLIER on<br/>relevance, not an override.<br/>An irrelevant featured provider<br/>must NOT outrank a relevant one.
    SRCH-->>API: Ranked IDs
    API->>DB: Hydrate current data by ID
    Note over API,DB: Index is for ranking only.<br/>Authoritative data from DB —<br/>a stale index must never show<br/>a suspended provider as active.
    API->>API: Filter: active + approved + subscription current
    API-->>U: Results + featured badge
    end

    rect rgb(255,240,240)
    alt Search engine unavailable — QAS-AVL-04
        API->>DB: Fallback: DB-backed filtered listing
        API-->>U: Degraded results, not an error page
    end
    end

flowchart TB
    REQ["Incoming authenticated request"] --> AUTH["Authenticate<br/>→ resolve user + org context"]
    AUTH --> CTX["Bind tenant context<br/>to the request scope"]
    CTX --> POL["Policy / Gate check<br/><i>coarse-grained capability</i>"]
    POL --> QRY["Repository / query executed"]

    QRY --> SCOPE{"Global tenant scope<br/>auto-applied?"}
    SCOPE -->|"Yes — default"| SAFE["✅ Query constrained<br/>to tenant"]
    SCOPE -->|"Explicitly bypassed"| GUARD{"Bypass on the<br/>allow-list?<br/><i>admin / system context</i>"}
    GUARD -->|Yes| AUDIT["✅ Permitted<br/>📝 audit-logged"]
    GUARD -->|No| FAIL["🚨 FAIL CLOSED<br/>Exception + alert"]

    SAFE --> RESP["Response"]
    AUDIT --> RESP
    FAIL --> ERR["500 + security event<br/><i>never silently unscoped</i>"]

    style FAIL fill:#c94a4a,stroke:#8b2f2f,color:#fff
    style ERR fill:#c94a4a,stroke:#8b2f2f,color:#fff
    style SAFE fill:#2d8659,stroke:#1c5638,color:#fff
    style AUDIT fill:#2d8659,stroke:#1c5638,color:#fff