arc42 §6b — Feature Data Flows: Core Platform

flowchart TB
    subgraph SRC["Data Sources"]
        U["👤 Users<br/>5 actor types"]
        ADM["🛡️ Admins"]
        EXT["🔌 External<br/>payment · video · SMS"]
    end

    subgraph P1["Pipeline 1 — Transactional (synchronous)"]
        direction LR
        API1["API"] --> VAL["Validate<br/>+ AuthZ<br/>+ Tenant scope"] --> TX[("PostgreSQL<br/>ACID")]
    end

    subgraph P2["Pipeline 2 — Document (async, untrusted)"]
        direction LR
        UP["Upload"] --> QUAR["Quarantine<br/>bucket"] --> SCAN["Malware<br/>scan"] --> PROM["Promote"] --> STORE[("Object Storage<br/>encrypted")]
    end

    subgraph P3["Pipeline 3 — Generation (async, burst)"]
        direction LR
        TRIG["Trigger"] --> JQ["Job queue"] --> REND["Render<br/>Arabic-capable"] --> ART[("Artifacts<br/>certificates · docs")]
    end

    subgraph P4["Pipeline 4 — Projection (async, eventually consistent)"]
        direction LR
        EVT["Domain<br/>events"] --> OUT["Outbox"] --> PROJ["Projectors"]
        PROJ --> IDX[("Search index")]
        PROJ --> RPT[("Reporting<br/>read model")]
        PROJ --> NOT["Notifications"]
    end

    U --> API1
    ADM --> API1
    EXT -->|"webhooks<br/>signature-verified<br/>idempotent"| API1
    U --> UP
    TX -.->|"emits"| EVT
    TX -.->|"triggers"| TRIG
    STORE -.-> REND
    ART --> STORE

    style P1 fill:#e8f0fe,stroke:#1168bd
    style P2 fill:#fde8e8,stroke:#c94a4a
    style P3 fill:#e8f5e9,stroke:#2d8659
    style P4 fill:#fff4e5,stroke:#d98c1f

flowchart TB
    START["User opens app"] --> CHOOSE{"Select<br/>account type"}

    CHOOSE -->|Individual| I1["Collect: name, email/phone<br/>Optional: profession"]
    CHOOSE -->|Company| C1["Collect: company name, CR number,<br/>contact person, city, business type"]
    CHOOSE -->|Consultant| K1["Collect: name, specialties,<br/>credentials, bio"]
    CHOOSE -->|Service Provider| S1["Collect: company name, CR,<br/>service categories, coverage area"]

    I1 --> VERIFY["Verify identity channel<br/>OTP or Google ID token"]
    C1 --> VERIFY
    K1 --> VERIFY
    S1 --> VERIFY

    VERIFY --> CREATE["Create user + type-specific profile<br/><i>one transaction</i>"]

    CREATE --> GATE{"Approval<br/>required?<br/><i>CON-04</i>"}

    GATE -->|"Individual — No"| ACTIVE["✅ state: active<br/>Full access to<br/>individual capabilities"]
    GATE -->|"Company / Consultant /<br/>Provider — Yes"| PENDING["⏳ state: pending_documents"]

    PENDING --> DOCS["Prompt: upload legal documents<br/><i>→ Flow 2 in 06</i>"]
    DOCS --> REVIEW["state: under_review"]
    REVIEW --> DECIDE{"Admin<br/>decision"}
    DECIDE -->|Approved| ACTIVE2["✅ state: active"]
    DECIDE -->|Rejected| REJ["❌ state: rejected + reason"]
    REJ --> RESUB["Resubmission allowed<br/><i>new document version</i>"]
    RESUB --> REVIEW

    ACTIVE --> CAP["Capabilities resolved from<br/>actor type + account state"]
    ACTIVE2 --> CAP

    style PENDING fill:#fff4e5,stroke:#d98c1f
    style REJ fill:#fde8e8,stroke:#c94a4a
    style ACTIVE fill:#e8f5e9,stroke:#2d8659
    style ACTIVE2 fill:#e8f5e9,stroke:#2d8659

flowchart LR
    subgraph EDIT["Edit request"]
        REQ["PATCH /v1/profile"] --> AUTHZ{"Who is<br/>editing?"}
    end

    AUTHZ -->|"Self — Individual/Consultant/Provider"| FULL["Full profile fields<br/>editable"]
    AUTHZ -->|"Self — Employee"| LIMITED["⚠ LIMITED fields only<br/><i>BRD §11: 'Limited'</i><br/>name, phone, password, locale"]
    AUTHZ -->|"Company admin editing employee"| CO["Employment fields only<br/>NOT credentials"]
    AUTHZ -->|"Platform admin"| ADMIN["All fields<br/>📝 audit-logged"]

    FULL --> SENSITIVE{"Sensitive<br/>field?"}
    LIMITED --> SENSITIVE
    CO --> APPLY
    ADMIN --> APPLY

    SENSITIVE -->|"email / phone"| REVERIFY["Re-verify channel<br/>before applying"]
    SENSITIVE -->|"password"| REVOKE["Apply + revoke<br/>ALL token families"]
    SENSITIVE -->|"No"| APPLY["Apply change"]

    REVERIFY --> APPLY
    REVOKE --> APPLY
    APPLY --> REINDEX["Emit ProfileUpdated<br/>→ reindex if listing-visible"]

    style LIMITED fill:#fff4e5,stroke:#d98c1f
    style REVOKE fill:#fde8e8,stroke:#c94a4a

sequenceDiagram
    autonumber
    participant CO as 🏢 Company Admin
    participant API as Qwizin API
    participant DB as PostgreSQL
    participant N as Notifications
    participant EMP as 👷 Employee

    CO->>API: POST /v1/company/employees {name, email/phone, job title}
    API->>API: AuthZ: is company_admin AND company.state == active
    Note over API: ⚠ CON-09: employee cannot exist<br/>under a non-approved company
    API->>DB: BEGIN TX
    API->>DB: Create user(actor_type: employee, state: invited)
    API->>DB: Link employment(company_id, employee_id, job_title)
    API->>DB: 📝 Audit: admin X created employee Y
    API->>DB: COMMIT
    API->>N: Dispatch invitation
    N->>EMP: 🔔 Invitation + one-time activation link

    EMP->>API: Activate {token, set password}
    API->>API: Validate token (single-use, expiring)
    API->>DB: user.state = active
    API-->>EMP: {access_token, refresh_token}

    rect rgb(255,240,240)
    Note over CO,EMP: ⚠ Cascade — OQ-07 UNRESOLVED
    CO->>API: Deactivate employee
    API->>DB: employment.state = terminated
    API->>DB: Revoke all token families
    Note over DB: Open: what happens to<br/>in-flight assessments?<br/>Already-issued certificates?<br/>→ OQ-07 needs a sponsor ruling
    end

stateDiagram-v2
    [*] --> pending_documents: Registration complete<br/>(approval-gated types)
    [*] --> active: Registration complete<br/>(Individual)

    pending_documents --> under_review: All required documents<br/>uploaded + scanned clean
    under_review --> active: ✅ Admin approves ALL<br/>required documents
    under_review --> rejected: ❌ Admin rejects<br/>(reason required)
    rejected --> pending_documents: User resubmits<br/>(new document version)

    active --> suspended: Admin action /<br/>subscription lapse
    suspended --> active: Reinstated
    active --> closed: User or admin closes
    suspended --> closed: Escalation

    closed --> [*]

    note right of under_review
        Activation requires ALL required
        documents approved — not the first.
        Partial approval keeps the account
        in under_review.
    end note

    note right of rejected
        Resubmission creates document
        version n+1. NEVER overwrites n —
        the evidence behind the original
        decision must survive (QAS-CMP-02).
    end note

flowchart TB
    subgraph IDX["Indexing — async, Pipeline 4"]
        CE["Consultant approved /<br/>profile updated /<br/>availability changed"] --> DEB["Debounce"]
        DEB --> IX[("Search index<br/>name_ar · name_en · specialties ·<br/>city · price_band · rating · languages")]
    end

    subgraph BROWSE["Browse — Pipeline 1"]
        Q["GET /v1/consultants<br/>?specialty=&amp;city=&amp;type=&amp;q="] --> NORM["Normalise Arabic query"]
        NORM --> SR["Query index"]
        SR --> HYD["Hydrate from DB by ID"]
        HYD --> FILT["⚠ Post-filter:<br/>state == active<br/>AND approved"]
        FILT --> RES["Ranked results"]
    end

    subgraph PROFILE["Consultant detail"]
        RES --> DET["GET /v1/consultants/{id}"]
        DET --> PUB["Public: bio, specialties,<br/>credentials, pricing,<br/>consultation types offered"]
        DET --> AVAIL["Availability calendar<br/><i>⚠ OQ-03</i>"]
    end

    style FILT fill:#fde8e8,stroke:#c94a4a
    style AVAIL fill:#fff4e5,stroke:#d98c1f

sequenceDiagram
    autonumber
    participant C as 👤 Customer
    participant API as Qwizin API
    participant CON as 🎓 Consultant
    participant PAY as 💳 Payment
    participant N as Notifications

    C->>API: POST /v1/bookings {type: on_site, consultant, preferred dates[], site address, scope notes}
    API->>API: Validate: consultant offers on_site<br/>+ covers this city
    Note over API: ⚠ Coverage area is a<br/>consultant profile attribute —<br/>on-site is geographically bounded
    API->>DB: booking(type: on_site, state: pending_quote)

    rect rgb(255,245,235)
    Note over CON,PAY: Quotation — on-site pricing is not a fixed rate
    API->>CON: 🔔 On-site request + scope
    CON->>API: Provide quote {fee, travel cost, duration, date}
    API->>C: 🔔 Quote received
    alt Customer accepts
        C->>API: Accept quote
        API->>PAY: AUTHORIZE hold
        API->>DB: booking(state: confirmed)
    else Customer declines / no response
        API->>DB: booking(state: expired)
    end
    end

    rect rgb(240,255,240)
    Note over C,N: Visit & completion — NO automatic signal
    N->>C: 🔔 Reminder T-24h
    N->>CON: 🔔 Reminder T-24h
    Note over C,CON: Visit happens off-platform
    CON->>API: Mark visit completed + upload report
    C->>API: Confirm completion
    API->>PAY: CAPTURE
    Note over API,PAY: ⚠ Capture requires confirmation.<br/>Video sessions have provider webhooks;<br/>on-site has NOTHING — a human must<br/>assert it happened.
    end

    rect rgb(255,240,240)
    alt Dispute — customer says visit did not occur
        API->>API: Flag for admin resolution
        Note over API: ⚠ Policy undefined in all sources<br/>→ OQ-05
    end
    end

flowchart TB
    subgraph PUB["Publishing — admin, Pipeline 1+2"]
        A["🛡️ Admin uploads template"] --> META["Capture structured metadata:<br/>title_ar/en · category · subcategory ·<br/>description · file format · version"]
        META --> SCAN2["Malware scan"]
        SCAN2 --> STORE[("Object Storage<br/>templates/")]
        META --> DBT[("templates table")]
        DBT --> IXT["→ Search index"]
    end

    subgraph BR["Browse — Pipeline 1"]
        U["Any authenticated user<br/><i>all types — BR-RL-2</i>"] --> CAT["GET /v1/templates?category="]
        CAT --> LIST["Category tree + listings"]
        LIST --> DET2["GET /v1/templates/{id}"]
    end

    subgraph DL["Download"]
        DET2 --> DLREQ["POST /v1/templates/{id}/download"]
        DLREQ --> AUTHZ2["AuthZ: authenticated<br/><i>no payment gate</i>"]
        AUTHZ2 --> LOG["📊 Record download event<br/><i>KPI: templates downloaded</i>"]
        LOG --> SIGN["Issue signed URL, short TTL"]
        SIGN --> FETCH["Client fetches DIRECTLY<br/>from object storage"]
    end

    style FETCH fill:#e8f5e9,stroke:#2d8659

erDiagram
    TEMPLATE ||--o{ TEMPLATE_SECTION : contains
    TEMPLATE_SECTION ||--o{ TEMPLATE_ITEM : contains
    TEMPLATE ||--o{ TEMPLATE_FILE : "has renditions"
    TEMPLATE {
        id id
        string title_ar
        string title_en
        string category
        int version
        enum kind "document | checklist | form"
    }
    TEMPLATE_SECTION {
        id id
        string title_ar
        string title_en
        int order
    }
    TEMPLATE_ITEM {
        id id
        text prompt_ar
        text prompt_en
        enum response_type "yes_no | na | text | numeric"
        bool required
    }
    TEMPLATE_FILE {
        id id
        string format "xlsx | pdf | docx"
        string storage_ref
    }

sequenceDiagram
    autonumber
    participant U as 👤 Customer
    participant API as Qwizin API
    participant PAY as 💳 Payment
    participant ADM as 🛡️ Admin
    participant SPC as ✍️ Specialist
    participant OBJ as Object Storage
    participant N as Notifications

    rect rgb(240,240,255)
    Note over U,API: Intake — CON-11: MINIMAL steps
    U->>API: POST /v1/template-requests<br/>{base_template_id?, business_type, business_size,<br/>requirements_text, attachments?}
    Note over U,API: ⚠ Deliberately short form.<br/>Every extra field costs conversion<br/>on a paid action.
    API->>DB: request(state: submitted)
    API->>API: Determine price<br/><i>fixed / tiered / quoted</i>
    end

    rect rgb(255,245,235)
    Note over U,PAY: Payment
    alt Fixed or tiered price
        API-->>U: {price}
        U->>API: Pay {idempotency_key}
        API->>PAY: AUTHORIZE + CAPTURE
        Note over API,PAY: Capture immediately — unlike bookings,<br/>there is no counterparty acceptance step
        API->>DB: request(state: paid)
    else Quote required
        API->>ADM: 🔔 Quote needed
        ADM->>API: Provide quote
        API->>U: 🔔 Quote
        U->>API: Accept + pay
        API->>DB: request(state: paid)
    end
    end

    rect rgb(240,255,240)
    Note over ADM,OBJ: Fulfilment — HUMAN work, off-platform
    API->>ADM: 🔔 New paid request in queue
    ADM->>API: Assign to specialist
    API->>DB: request(state: in_progress, assignee, due_date)
    N->>U: 🔔 In progress, expected by {date}
    SPC->>API: Upload deliverable
    API->>API: Malware scan (Pipeline 2)
    API->>OBJ: Store → deliverables/
    API->>DB: request(state: delivered)
    N->>U: 🔔 Ready for download
    U->>API: Download via signed URL
    API->>DB: 📊 Record delivery acceptance
    end

    rect rgb(255,240,240)
    alt Revision requested
        U->>API: Request revision {notes}
        API->>DB: request(state: revision_requested)
        Note over API: ⚠ How many revisions are included?<br/>Undefined in all sources → OQ-14
    end
    end

flowchart TB
    subgraph AUTHOR["Content authoring — Admin"]
        A1["🛡️ Admin creates learning content"] --> A2["Structured: module → lessons<br/>title_ar/en · body_ar/en · order ·<br/>estimated_duration · category"]
        A2 --> A3["Link assessment<br/><i>MOD-ASMT</i>"]
        A3 --> A4["Publish → available to assign"]
    end

    subgraph ASSIGN["Assignment — Company Admin"]
        B1["🏢 Company admin selects content"] --> B2["Select employees<br/><i>individual / all / by job title</i>"]
        B2 --> B3["Set due date (optional)"]
        B3 --> B4["Create assignment records<br/><i>one per employee</i>"]
        B4 --> B5["🔔 Notify employees"]
    end

    subgraph LEARN["Learning — Employee"]
        C1["👷 Employee opens assigned module"] --> C2["Read lesson content"]
        C2 --> C3["Mark lesson complete"]
        C3 --> C4{"All lessons<br/>complete?"}
        C4 -->|No| C2
        C4 -->|Yes| C5["Unlock assessment"]
        C5 --> C6["→ Flow 4: MCQ assessment"]
    end

    subgraph TRACK["Progress — Company Admin"]
        D1["Progress events"] --> D2[("Progress read model<br/>Pipeline 4")]
        D2 --> D3["Company dashboard:<br/>assigned · started · completed ·<br/>passed · certificate issued"]
    end

    A4 --> B1
    B5 --> C1
    C3 -.->|"emits LessonCompleted"| D1
    C6 -.->|"emits AssessmentPassed"| D1

    style C6 fill:#e8f0fe,stroke:#1168bd

erDiagram
    LEARNING_MODULE ||--o{ LESSON : contains
    LEARNING_MODULE ||--o| ASSESSMENT : "gated by"
    LEARNING_MODULE ||--o{ ASSIGNMENT : "assigned via"
    ASSIGNMENT }o--|| EMPLOYEE : "to"
    ASSIGNMENT ||--o{ LESSON_PROGRESS : tracks
    ASSIGNMENT {
        id id
        id company_id "tenant scope"
        id employee_id
        id module_id
        date due_date
        enum state "assigned|in_progress|completed|overdue"
        timestamp assigned_at
    }
    LESSON_PROGRESS {
        id assignment_id
        id lesson_id
        timestamp completed_at
    }