Kinloch Platform

C4 Architecture Model & Behavioral Flows | v1 Scope | April 2026

2
Actors
8
External Systems
7
Containers
34
Components
15
Flows

System Context Diagram C4 Level 1

High-level view showing the Kinloch Platform, its users, and external system dependencies

Person
Kinloch Platform
External System
flowchart TD
    patient["Patient
Cannabis healthcare patient"]
    np["Nurse Practitioner
Licensed NP who reviews and authorizes"]
    kinloch["Kinloch Platform
Discovery, AI intake, NP authorization,
compliant cannabis access"]
    shopify["Shopify
Product catalogue, payments, fulfillment"]
    llm["AI / LLM Provider
Clinical summary generation"]
    voiceai["Voice AI Platform
Conversational voice intake"]
    sms["SMS Provider
2FA and notifications"]
    idv["IDV Provider
Identity verification"]
    college["Provincial College Registry
License verification"]
    hc["Health Canada
Regulatory reporting"]
    marketing["Marketing Platform
Paid media, SEO, CRM"]

    patient -->|uses| kinloch
    np -->|uses| kinloch
    kinloch -->|integrates| shopify
    kinloch -->|generates summaries| llm
    kinloch -->|voice intake| voiceai
    kinloch -->|sends SMS| sms
    kinloch -->|verifies identity| idv
    kinloch -->|verifies licenses| college
    kinloch -->|submits reports| hc
    marketing -->|drives traffic| kinloch

    style patient fill:#08427b,stroke:#073b6e,color:#fff
    style np fill:#08427b,stroke:#073b6e,color:#fff
    style kinloch fill:#1168bd,stroke:#0e5aa7,color:#fff
    style shopify fill:#999,stroke:#777,color:#fff
    style llm fill:#999,stroke:#777,color:#fff
    style voiceai fill:#999,stroke:#777,color:#fff
    style sms fill:#999,stroke:#777,color:#fff
    style idv fill:#999,stroke:#777,color:#fff
    style college fill:#999,stroke:#777,color:#fff
    style hc fill:#999,stroke:#777,color:#fff
    style marketing fill:#999,stroke:#777,color:#fff

Container Diagram C4 Level 2

Internal structure of the Kinloch Platform showing all deployable containers and their interactions

Person
Container
External System
flowchart TD
    patient["Patient"]
    np["Nurse Practitioner"]

    subgraph kinloch["Kinloch Platform"]
        webapp["Patient Web App
React
Discovery, cart, account, dashboard"]
        npapp["NP Workbench
Responsive Web
Case queue, review, authorization"]
        api["Platform API
REST API
Auth, commerce, registration, orchestration"]
        intake["AI Clinical Intake Engine
AI Service
Questionnaire, voice, clinical summary"]
        compliance["Compliance Service
Backend
Registration, ledger, reporting"]
        db[("Application Database
PostgreSQL, AES-256")]
        storage[("Object Storage
S3, AES-256")]
    end

    shopify["Shopify"]
    llm["AI/LLM Provider"]
    voiceai["Voice AI Platform"]
    sms["SMS Provider"]
    idv["IDV Provider"]
    college["Provincial College Registry"]
    hc["Health Canada"]

    patient -->|browses, orders| webapp
    np -->|reviews, authorizes| npapp
    webapp -->|REST/JSON| api
    webapp -->|embedded buy flow| shopify
    npapp -->|REST/JSON| api
    api -->|SQL| db
    api -->|Shopify API| shopify
    api -->|2FA SMS| sms
    api --> intake
    api --> compliance
    intake -->|SQL| db
    intake --> storage
    intake -->|LLM API| llm
    intake -->|voice API| voiceai
    intake -->|callback SMS| sms
    compliance -->|SQL| db
    compliance -->|API| idv
    compliance -->|API| college
    compliance --> hc

    style patient fill:#08427b,stroke:#073b6e,color:#fff
    style np fill:#08427b,stroke:#073b6e,color:#fff
    style webapp fill:#438dd5,stroke:#3a7bc0,color:#fff
    style npapp fill:#438dd5,stroke:#3a7bc0,color:#fff
    style api fill:#438dd5,stroke:#3a7bc0,color:#fff
    style intake fill:#438dd5,stroke:#3a7bc0,color:#fff
    style compliance fill:#438dd5,stroke:#3a7bc0,color:#fff
    style db fill:#438dd5,stroke:#3a7bc0,color:#fff
    style storage fill:#438dd5,stroke:#3a7bc0,color:#fff
    style kinloch fill:#0d1b2a,stroke:#1e3a5f,color:#fff
    style shopify fill:#999,stroke:#777,color:#fff
    style llm fill:#999,stroke:#777,color:#fff
    style voiceai fill:#999,stroke:#777,color:#fff
    style sms fill:#999,stroke:#777,color:#fff
    style idv fill:#999,stroke:#777,color:#fff
    style college fill:#999,stroke:#777,color:#fff
    style hc fill:#999,stroke:#777,color:#fff

Patient Web Application — Components C4 Level 3

9 components: discovery, commerce, account management, and patient dashboard

flowchart LR
    patient["Patient"]

    subgraph webapp["Patient Web Application"]
        wheel["Kinloch Wheel
Terpene education, recommendations"]
        browse["Product Browse Page
Product grid, filters, details"]
        agegate["Age Verification Gate
Cannabis content gate [Extended]"]
        cart["Shopping Cart
Persistent cart, restoration"]
        checkout["Checkout Gate
Auth lock/unlock logic"]
        signup["Account Creation Flow
3-screen form, email verify"]
        login["Login and Session Mgmt
Email/password, sessions"]
        twofa["Two-Step Verification
SMS, authenticator, backup codes"]
        dashboard["Patient Dashboard
Auth status, orders, settings"]
    end

    api["Platform API
REST API"]
    shopify["Shopify"]

    patient --> wheel
    patient --> dashboard
    wheel --> api
    browse --> api
    agegate --> api
    cart --> api
    cart --> shopify
    checkout --> api
    signup --> api
    login --> api
    twofa --> api
    dashboard --> api

    style patient fill:#08427b,stroke:#073b6e,color:#fff
    style webapp fill:#0d1b2a,stroke:#1e3a5f,color:#fff
    style api fill:#438dd5,stroke:#3a7bc0,color:#fff
    style shopify fill:#999,stroke:#777,color:#fff
    style wheel fill:#85bbf0,stroke:#6fa8e0,color:#000
    style browse fill:#85bbf0,stroke:#6fa8e0,color:#000
    style agegate fill:#85bbf0,stroke:#6fa8e0,color:#000
    style cart fill:#85bbf0,stroke:#6fa8e0,color:#000
    style checkout fill:#85bbf0,stroke:#6fa8e0,color:#000
    style signup fill:#85bbf0,stroke:#6fa8e0,color:#000
    style login fill:#85bbf0,stroke:#6fa8e0,color:#000
    style twofa fill:#85bbf0,stroke:#6fa8e0,color:#000
    style dashboard fill:#85bbf0,stroke:#6fa8e0,color:#000

NP Workbench — Components C4 Level 3

6 components: case management, clinical review, authorization decisions, and NP operations

flowchart LR
    np["Nurse Practitioner"]

    subgraph npapp["NP Workbench"]
        queue["Case Queue Dashboard
Queue view, filters, risk levels"]
        review["Case Review Interface
3-column: summary, meds, decision"]
        decision["Decision Workflow
Approve/decline/flag, e-signature"]
        dispatch["NP Dispatch and Notification
Assignment, claim window, escalation"]
        avail["NP Availability Mgmt
Online/idle/offline, queue depth"]
        comp["NP Compensation Tracking
Per-case earnings, case history"]
    end

    api["Platform API
REST API"]

    np --> queue
    np --> review
    queue --> api
    review --> api
    decision --> api
    dispatch --> api
    avail --> api
    comp --> api

    style np fill:#08427b,stroke:#073b6e,color:#fff
    style npapp fill:#0d1b2a,stroke:#1e3a5f,color:#fff
    style api fill:#438dd5,stroke:#3a7bc0,color:#fff
    style queue fill:#85bbf0,stroke:#6fa8e0,color:#000
    style review fill:#85bbf0,stroke:#6fa8e0,color:#000
    style decision fill:#85bbf0,stroke:#6fa8e0,color:#000
    style dispatch fill:#85bbf0,stroke:#6fa8e0,color:#000
    style avail fill:#85bbf0,stroke:#6fa8e0,color:#000
    style comp fill:#85bbf0,stroke:#6fa8e0,color:#000

Platform API — Components C4 Level 3

7 backend service components handling discovery, commerce, auth, registration, and NP workflow

flowchart TD
    webapp["Patient Web App"]
    npapp["NP Workbench"]

    subgraph api["Platform API"]
        discovery["Discovery Service
Recommendation engine, product matching"]
        commerce["Commerce Service
Cart persistence, checkout, Shopify integration"]
        auth["Auth Service
Account creation, login, sessions, 2FA"]
        registration["Patient Registration Engine
Unique patient ID, expiry management"]
        authstatus["Authorization Status API
Active/expired/pending/none + expiry"]
        orders["Order and Fulfillment Service
Order status and tracking from Shopify"]
        npworkflow["NP Workflow Service
Case assignment, dispatch, availability"]
    end

    db[("Application Database
PostgreSQL")]
    shopify["Shopify"]
    sms["SMS Provider"]
    intake["AI Clinical Intake Engine"]
    compliance["Compliance Service"]

    discovery --> db
    commerce --> db
    commerce --> shopify
    auth --> db
    auth --> sms
    registration --> db
    authstatus --> db
    orders --> shopify
    npworkflow --> db
    npworkflow --> sms
    npworkflow --> intake
    npworkflow --> compliance

    style webapp fill:#438dd5,stroke:#3a7bc0,color:#fff
    style npapp fill:#438dd5,stroke:#3a7bc0,color:#fff
    style api fill:#0d1b2a,stroke:#1e3a5f,color:#fff
    style db fill:#438dd5,stroke:#3a7bc0,color:#fff
    style shopify fill:#999,stroke:#777,color:#fff
    style sms fill:#999,stroke:#777,color:#fff
    style intake fill:#438dd5,stroke:#3a7bc0,color:#fff
    style compliance fill:#438dd5,stroke:#3a7bc0,color:#fff
    style discovery fill:#85bbf0,stroke:#6fa8e0,color:#000
    style commerce fill:#85bbf0,stroke:#6fa8e0,color:#000
    style auth fill:#85bbf0,stroke:#6fa8e0,color:#000
    style registration fill:#85bbf0,stroke:#6fa8e0,color:#000
    style authstatus fill:#85bbf0,stroke:#6fa8e0,color:#000
    style orders fill:#85bbf0,stroke:#6fa8e0,color:#000
    style npworkflow fill:#85bbf0,stroke:#6fa8e0,color:#000

AI Clinical Intake Engine — Components C4 Level 3

4 components: questionnaire, voice recording, AI summary generation, and callback scheduling

flowchart LR
    api["Platform API
Orchestrates intake"]

    subgraph intake["AI Clinical Intake Engine"]
        questionnaire["Questionnaire Engine
46 questions, 9 phases
Form + callback paths"]
        voice["Voice Recording Manager
Voice capture, transcripts
Encrypted storage"]
        summary["Clinical Summary Generator
AI summary, contraindication flags
Completeness score"]
        callback["Callback Scheduler
Callback windows, 1-hour retry
SMS fallback"]
    end

    db[("Application Database
PostgreSQL")]
    storage[("Object Storage
S3")]
    llm["AI/LLM Provider
OpenAI, Anthropic"]
    voiceai["Voice AI Platform
Twilio Voice, Vapi"]
    sms["SMS Provider
Twilio"]

    questionnaire --> db
    voice --> storage
    voice --> voiceai
    summary --> llm
    summary --> db
    callback --> sms

    style api fill:#438dd5,stroke:#3a7bc0,color:#fff
    style intake fill:#0d1b2a,stroke:#1e3a5f,color:#fff
    style db fill:#438dd5,stroke:#3a7bc0,color:#fff
    style storage fill:#438dd5,stroke:#3a7bc0,color:#fff
    style llm fill:#999,stroke:#777,color:#fff
    style voiceai fill:#999,stroke:#777,color:#fff
    style sms fill:#999,stroke:#777,color:#fff
    style questionnaire fill:#85bbf0,stroke:#6fa8e0,color:#000
    style voice fill:#85bbf0,stroke:#6fa8e0,color:#000
    style summary fill:#85bbf0,stroke:#6fa8e0,color:#000
    style callback fill:#85bbf0,stroke:#6fa8e0,color:#000

Compliance & Regulatory Service — Components C4 Level 3

8 components: medical documents, audit trail, regulatory reporting, IDV, and license verification

flowchart TD
    api["Platform API
Triggers compliance workflows"]

    subgraph compliance["Compliance and Regulatory Service"]
        meddoc["Medical Document Generator
Part 14 authorization, e-signature"]
        ledger["Compliance Ledger
WORM audit log, 1-year baseline"]
        amendment["Amendment and Revocation Engine
ss.137-139 workflows"]
        hcreport["Health Canada Reporter
Monthly s.297 reports, scheduler"]
        provincial["Provincial Disclosure Module
s.299 disclosure packs"]
        licensing["Licensing Notice Module
s.277 templated notices"]
        idvint["IDV Integration
Jumio/Persona/Veriff [Extended]"]
        licverify["Practitioner License Verification
Provincial college lookups [Extended]"]
    end

    db[("Application Database
PostgreSQL")]
    hc["Health Canada
Regulatory authority"]
    idv["IDV Provider"]
    college["Provincial College Registry"]

    meddoc --> db
    ledger --> db
    amendment --> db
    hcreport --> hc
    provincial --> hc
    licensing --> hc
    idvint --> idv
    licverify --> college

    style api fill:#438dd5,stroke:#3a7bc0,color:#fff
    style compliance fill:#0d1b2a,stroke:#1e3a5f,color:#fff
    style db fill:#438dd5,stroke:#3a7bc0,color:#fff
    style hc fill:#999,stroke:#777,color:#fff
    style idv fill:#999,stroke:#777,color:#fff
    style college fill:#999,stroke:#777,color:#fff
    style meddoc fill:#85bbf0,stroke:#6fa8e0,color:#000
    style ledger fill:#85bbf0,stroke:#6fa8e0,color:#000
    style amendment fill:#85bbf0,stroke:#6fa8e0,color:#000
    style hcreport fill:#85bbf0,stroke:#6fa8e0,color:#000
    style provincial fill:#85bbf0,stroke:#6fa8e0,color:#000
    style licensing fill:#85bbf0,stroke:#6fa8e0,color:#000
    style idvint fill:#85bbf0,stroke:#6fa8e0,color:#000
    style licverify fill:#85bbf0,stroke:#6fa8e0,color:#000

Patient Journey

End-to-end patient lifecycle from first visit through registration, discovery, and purchase

5. End-to-End Patient Journey Core

Complete lifecycle from first visit through discovery, intake, authorization, and first purchase

flowchart TD
    A([Marketing drives traffic]) --> B[Age Verification Gate]
    B --> C[Patient explores Kinloch Wheel]
    C --> D[Patient browses Product Browse Page]
    D --> E[Patient adds to Shopping Cart]
    E --> F[Checkout Gate blocks: no auth]
    F --> G[Account Creation Flow + 2FA]
    G --> H[Patient Registration Engine: unique ID]
    H --> I[AI Clinical Intake: 46 Qs, 9 phases]
    I --> J[Clinical Summary via AI/LLM]
    J --> K[NP Workflow Service assigns case]
    K --> L[NP reviews in Case Review Interface]
    L --> M[NP approves via Decision Workflow]
    M --> N[Medical Document: Part 14 auth]
    N --> O[Auth Status API: patient active]
    O --> P[Patient returns to Shopping Cart]
    P --> Q[Checkout Gate unlocks]
    Q --> R[Shopify processes payment]
    R --> S[Patient Dashboard: order + auth status]
    S --> T([Compliance Ledger: full audit trail])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style F fill:#3a2a1a,stroke:#ed8936,color:#fff
    style O fill:#1a3a2a,stroke:#48bb78,color:#fff
    style T fill:#1a3a2a,stroke:#48bb78,color:#fff

Detailed Steps

  1. Marketing & Content Platform drives Patient to Patient Web Application
  2. Age Verification Gate validates patient age for cannabis content access
  3. Patient explores products via Kinloch Wheel and Product Browse Page
  4. Patient adds products to Shopping Cart and attempts checkout
  5. Checkout Gate blocks purchase — no account or authorization exists
  6. Patient completes Account Creation Flow with email verification and Two-Step Verification
  7. Patient Registration Engine registers patient with unique identifier
  8. Patient initiates AI clinical intake via Questionnaire Engine (46 questions, 9 phases)
  9. Clinical Summary Generator produces structured summary via AI / LLM Provider
  10. NP Workflow Service assigns case to available Nurse Practitioner
  11. Nurse Practitioner reviews case in Case Review Interface and approves via Decision Workflow
  12. Medical Document Generator produces Part 14 authorization document with e-signature
  13. Authorization Status API updates patient to active authorization with expiry date
  14. Patient receives authorization notification and returns to Shopping Cart
  15. Checkout Gate confirms active authorization and unlocks checkout
  16. Shopify processes payment via embedded buy flow and initiates fulfillment
  17. Patient Dashboard displays active authorization, order status, and tracking
  18. Compliance Ledger records full audit trail: consent, intake, decision, document, and purchase events

4. Patient Registration & Account Setup Core

New patient creates account with age verification, email confirmation, and 2FA setup

flowchart TD
    A([Patient arrives]) --> B[Age Verification Gate]
    B --> C[Account Creation Flow: 3-screen form]
    C --> D[Identity fields collected]
    D --> E[Auth Service sends email verification]
    E --> F[Patient confirms email]
    F --> G[Patient Registration Engine: unique ID]
    G --> H{2FA Setup Method}
    H -->|SMS| I[Auth Service sends code via SMS Provider]
    I --> J[Patient enters SMS code]
    H -->|Authenticator| K[Auth Service generates QR code]
    K --> L[Patient scans QR and confirms]
    J --> M[Patient Dashboard: account ready]
    L --> M
    M --> N([Compliance Ledger: account creation recorded])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style H fill:#2d1b4e,stroke:#9f7aea,color:#fff
    style M fill:#1a3a2a,stroke:#48bb78,color:#fff
    style N fill:#1a3a2a,stroke:#48bb78,color:#fff

Detailed Steps

  1. Patient arrives at Patient Web Application and encounters Age Verification Gate
  2. Age Verification Gate validates patient meets age requirement for cannabis content
  3. Patient begins Account Creation Flow — 3-screen progressive form
  4. Account Creation Flow collects identity fields required for registration
  5. Auth Service sends email verification and creates account in Application Database
  6. Patient confirms email and completes registration
  7. Patient Registration Engine generates unique patient identifier and stores registration in Application Database
  8. Patient sets up Two-Step Verification
    • if: SMS verification:
      1. Auth Service sends verification code via SMS Provider
      2. Patient enters SMS code to confirm
    • if: authenticator app:
      1. Auth Service generates QR code for authenticator app setup
      2. Patient scans QR and confirms with generated code
  9. Patient accesses Patient Dashboard showing account status, empty order history, and authorization state (none)
  10. Compliance Ledger records account creation and consent events

6. Patient Login & Session Core

Returning patient authenticates with credentials and 2FA

flowchart TD
    A([Patient opens app]) --> B[Login and Session Management]
    B --> C[Patient enters email/password]
    C --> D{Auth Service validates}
    D -->|Valid| E[Two-Step Verification prompt]
    E --> F[Patient completes 2FA]
    F --> G[Persistent session established]
    G --> H([Patient Dashboard loaded])
    D -->|Invalid| I[Failed attempt counter incremented]
    I --> J[Error displayed, retry allowed]
    D -->|Account Locked| K[Login blocked]
    K --> L([Lockout message with recovery])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style D fill:#2d1b4e,stroke:#9f7aea,color:#fff
    style H fill:#1a3a2a,stroke:#48bb78,color:#fff
    style L fill:#742a2a,stroke:#fc8181,color:#fff

Detailed Steps

  1. Patient opens Patient Web Application and navigates to Login & Session Management
  2. Patient enters email and password
  3. Auth Service validates credentials against Application Database
    • if: credentials valid:
      1. Auth Service prompts for Two-Step Verification
      2. Patient completes 2FA via SMS code or authenticator app
      3. Auth Service establishes persistent session
      4. Patient lands on Patient Dashboard with auth status and order history
    • if: credentials invalid:
      1. Auth Service increments failed attempt counter
      2. Login & Session Management displays error and allows retry
    • if: account locked:
      1. Auth Service blocks login after excessive failed attempts
      2. Login & Session Management displays lockout message with recovery options

1. Patient Discovery & Purchase Core

Patient explores products via Kinloch Wheel, browses catalogue, adds to cart, and completes purchase through Shopify

flowchart TD
    A([Patient opens app]) --> B[Kinloch Wheel presents terpene education]
    B --> C[Discovery Service generates recommendations]
    C --> D[Patient browses Product Browse Page]
    D --> E[Patient adds to Shopping Cart]
    E --> F[Commerce Service persists cart]
    F --> G[Patient proceeds to Checkout Gate]
    G --> H{Authorization Status API check}
    H -->|Active Auth| I[Checkout Gate unlocks]
    I --> J[Shopify processes payment]
    J --> K[Order and Fulfillment Service gets data]
    K --> L([Patient Dashboard shows tracking])
    H -->|No Account / Expired| M[Checkout Gate blocks purchase]
    M --> N([Cart preserved for later])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style L fill:#1a3a2a,stroke:#48bb78,color:#fff
    style N fill:#3a2a1a,stroke:#ed8936,color:#fff
    style H fill:#2d1b4e,stroke:#9f7aea,color:#fff

Detailed Steps

  1. Patient opens Patient Web Application and lands on the Kinloch Wheel
  2. Kinloch Wheel presents terpene education and interactive experience selector
  3. Discovery Service generates real-time product recommendations based on patient selections
  4. Patient browses recommended products on Product Browse Page with filters and detail pages
  5. Patient adds products to Shopping Cart
  6. Shopping Cart persists cart state via Commerce Service
  7. Patient proceeds to checkout, hitting the Checkout Gate
  8. Checkout Gate queries Authorization Status API for auth state
    • if: active authorization:
      1. Checkout Gate unlocks and redirects to Shopify embedded buy flow
      2. Shopify processes payment and initiates fulfillment
      3. Order & Fulfillment Service retrieves order data from Shopify
      4. Patient Dashboard displays order status and tracking
    • if: no account or expired auth:
      1. Checkout Gate blocks purchase and prompts patient to register or complete clinical intake
      2. Shopping Cart preserves cart for restoration after authorization

15. Cart Restoration After Authorization Core

Preserved cart restored after patient completes authorization

flowchart TD
    A[Patient had items in cart] --> B[Checkout Gate blocked: no auth]
    B --> C[Commerce Service persists cart in DB]
    C --> D[Patient completes intake + NP authorization]
    D --> E[Auth Status API confirms active]
    E --> F[Patient returns to app]
    F --> G[Shopping Cart restores saved items]
    G --> H[Checkout Gate unlocks]
    H --> I([Shopify embedded buy flow])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style B fill:#3a2a1a,stroke:#ed8936,color:#fff
    style E fill:#1a3a2a,stroke:#48bb78,color:#fff
    style I fill:#1a3a2a,stroke:#48bb78,color:#fff

Detailed Steps

  1. Patient had items in Shopping Cart but was blocked by Checkout Gate due to missing authorization
  2. Commerce Service persists cart state in Application Database tied to patient account
  3. Patient completes clinical intake and receives NP authorization
  4. Authorization Status API confirms active authorization status
  5. Patient returns to Patient Web Application
  6. Shopping Cart restores previously saved cart items via Commerce Service
  7. Checkout Gate confirms active authorization and unlocks checkout
  8. Patient proceeds to Shopify embedded buy flow to complete purchase

Clinical Intake & Authorization

Core clinical workflow from AI intake through NP decision and case management

2. AI Clinical Intake Core

46-question, 9-phase AI clinical intake via form or voice, producing structured clinical summary for NP review

flowchart TD
    A([Patient initiates intake]) --> B[Platform API routes to AI Intake Engine]
    B --> C{Intake path selection}
    C -->|Form-based| D[Patient completes form UI]
    D --> E[Questionnaire Engine stores responses]
    C -->|Callback-based| F[Patient selects callback window]
    F --> G[Callback Scheduler sends SMS confirmation]
    G --> H[Voice AI Platform calls patient]
    H --> I[Voice Recording Manager captures audio]
    I --> J[Recordings stored in Object Storage]
    E --> K[Clinical Summary Generator calls LLM]
    J --> K
    K --> L[AI/LLM Provider returns structured summary]
    L --> M[Summary stored with contraindication flags]
    M --> N[Compliance Ledger records consent]
    N --> O([Case ready for NP review])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style C fill:#2d1b4e,stroke:#9f7aea,color:#fff
    style O fill:#1a3a2a,stroke:#48bb78,color:#fff

Detailed Steps

  1. Patient initiates clinical intake from Patient Web Application
  2. Platform API routes intake request to AI Clinical Intake Engine
  3. Questionnaire Engine presents 46-question, 9-phase clinical questionnaire
    • if: form-based path:
      1. Patient completes questionnaire via form UI in Patient Web Application
      2. Questionnaire Engine stores responses in Application Database
    • if: callback-based path:
      1. Patient selects preferred callback window
      2. Callback Scheduler schedules callback and confirms via SMS through SMS Provider
      3. Voice AI Platform initiates voice intake call at scheduled time
      4. Voice Recording Manager captures voice recording and generates transcript
      5. Voice Recording Manager stores encrypted recording in Object Storage
  4. Clinical Summary Generator sends intake data to AI / LLM Provider for processing
  5. AI / LLM Provider returns structured clinical summary with contraindication flags and completeness score
  6. Clinical Summary Generator stores summary in Application Database and marks case ready for NP review
  7. Compliance Ledger records intake consent and handoff event

7. Missed Callback & Retry Core

Patient misses scheduled callback, system retries after 1 hour, falls back to SMS

flowchart TD
    A[Callback Scheduler triggers call] --> B[Voice AI Platform calls patient]
    B --> C[Call goes unanswered]
    C --> D[Missed callback recorded in DB]
    D --> E[Wait 1 hour]
    E --> F[Voice AI Platform retries]
    F --> G{Patient answers?}
    G -->|Yes| H[Voice Recording Manager begins intake]
    H --> I([Questionnaire continues])
    G -->|No| J[SMS fallback via SMS Provider]
    J --> K([Patient gets link to reschedule])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style G fill:#2d1b4e,stroke:#9f7aea,color:#fff
    style I fill:#1a3a2a,stroke:#48bb78,color:#fff
    style K fill:#3a2a1a,stroke:#ed8936,color:#fff

Detailed Steps

  1. Callback Scheduler triggers callback at patient-selected time via Voice AI Platform
  2. Voice AI Platform attempts to reach Patient — call goes unanswered
  3. Callback Scheduler records missed callback in Application Database
  4. Callback Scheduler waits 1 hour and initiates retry via Voice AI Platform
  5. Voice AI Platform attempts second call to Patient
    • if: patient answers:
      1. Voice Recording Manager begins voice intake recording
      2. Questionnaire Engine continues intake from where patient left off
    • if: missed again:
      1. Callback Scheduler sends SMS fallback via SMS Provider with link to reschedule
      2. Patient receives SMS and can reschedule or switch to form-based intake

13. NP Dispatch & Case Assignment Core

New case assigned to available NP with claim window, escalation, and notification

flowchart TD
    A[Clinical Summary marks case ready] --> B[Check NP Availability Management]
    B --> C[NP Dispatch assigns to best-match NP]
    C --> D[Push/SMS notification via SMS Provider]
    D --> E{NP responds?}
    E -->|Claims within window| F[Case locked to NP]
    F --> G([Case Queue Dashboard updated])
    E -->|Claim window expires| H[Escalation logic triggered]
    H --> I[Reassign to next available NP]
    I --> J([New notification sent])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style E fill:#2d1b4e,stroke:#9f7aea,color:#fff
    style G fill:#1a3a2a,stroke:#48bb78,color:#fff
    style J fill:#3a2a1a,stroke:#ed8936,color:#fff

Detailed Steps

  1. Clinical Summary Generator marks intake case as ready for NP review
  2. NP Workflow Service checks NP Availability Management for online NPs with capacity
  3. NP Dispatch & Notification assigns case to best-match NP and opens claim window
  4. NP Dispatch & Notification sends push/SMS notification to assigned NP via SMS Provider
  5. Nurse Practitioner receives notification
    • if: NP claims within window:
      1. NP Workflow Service locks case to claiming NP
      2. Case Queue Dashboard updates queue to reflect claimed case
    • if: claim window expires:
      1. NP Dispatch & Notification triggers escalation logic
      2. NP Workflow Service reassigns case to next available NP
      3. NP Dispatch & Notification sends notification to newly assigned NP

3. NP Authorization Workflow Core

NP reviews AI-generated clinical summary, makes authorization decision, generates medical document

flowchart TD
    A[NP Workflow Service assigns case] --> B[SMS notification to NP]
    B --> C([NP opens Workbench])
    C --> D[Case Queue Dashboard shows queue]
    D --> E[NP claims case]
    E --> F[Case Review Interface: 3-column view]
    F --> G[NP reviews summary and flags]
    G --> H{NP Decision}
    H -->|Approve| I[Medical Document Generator: Part 14 doc]
    I --> J[NP applies e-signature]
    J --> K[Auth Status API: patient = active]
    K --> L[Patient notified: authorized]
    H -->|Decline| M[Decision Workflow records refusal]
    M --> N[Amendment Engine: ss.137-139]
    N --> O[Patient notified: declined]
    H -->|Flag| P[Case flagged for escalation]
    P --> Q[NP Dispatch escalates to senior NP]
    L --> R[Compliance Ledger records events]
    O --> R
    Q --> R
    R --> S([NP Compensation logged])
    style C fill:#1a365d,stroke:#3182ce,color:#fff
    style H fill:#2d1b4e,stroke:#9f7aea,color:#fff
    style L fill:#1a3a2a,stroke:#48bb78,color:#fff
    style O fill:#742a2a,stroke:#fc8181,color:#fff
    style S fill:#1a3a2a,stroke:#48bb78,color:#fff

Detailed Steps

  1. NP Workflow Service assigns new case and sends notification to available Nurse Practitioner via SMS Provider
  2. Nurse Practitioner opens NP Workbench and views Case Queue Dashboard
  3. Case Queue Dashboard displays queue with case filters, risk levels, and wait times
  4. Nurse Practitioner claims a case and opens Case Review Interface
  5. Case Review Interface displays three-column view: clinical summary, contraindication panel, and medication review
  6. Nurse Practitioner reviews AI-generated summary, transcript, and contraindication flags
  7. Nurse Practitioner submits decision via Decision Workflow
    • if: approved:
      1. Medical Document Generator produces authorization document under Part 14
      2. Nurse Practitioner applies e-signature to medical document
      3. Authorization Status API updates patient status to active with expiry date
      4. Patient receives notification that authorization is active
    • if: declined:
      1. Decision Workflow records refusal reason
      2. Amendment & Revocation Engine initiates refusal workflow under ss.137-139
      3. Patient receives notification of decline with explanation
    • if: flagged for review:
      1. Decision Workflow flags case with notes for escalation
      2. NP Dispatch & Notification escalates to senior NP
  8. Compliance Ledger records decision, document generation, and handoff events
  9. NP Compensation Tracking logs completed case for NP earnings

8. Authorization Amendment & Revocation Regulatory

Active authorization amended or revoked under Cannabis Regulations ss.137-139

flowchart TD
    A([NP initiates from Workbench]) --> B[Amendment Engine loads authorization]
    B --> C{Action type}
    C -->|Amendment| D[Record amendment details]
    D --> E[Medical Document Generator: amended doc]
    E --> F[Auth Status API: updated terms]
    C -->|Revocation| G[Record revocation reason: ss.137-139]
    G --> H[Auth Status API: expired immediately]
    H --> I[Checkout Gate blocks future purchases]
    F --> J[Patient notified via Dashboard]
    I --> J
    J --> K[Compliance Ledger: audit trail]
    K --> L([Licensing Notice Module: s.277 if required])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style C fill:#2d1b4e,stroke:#9f7aea,color:#fff
    style I fill:#742a2a,stroke:#fc8181,color:#fff
    style L fill:#1a3a2a,stroke:#48bb78,color:#fff

Detailed Steps

  1. Nurse Practitioner initiates amendment or revocation from NP Workbench
  2. Amendment & Revocation Engine loads active authorization from Application Database
  3. Nurse Practitioner selects action type
    • if: amendment:
      1. Amendment & Revocation Engine records amendment details (dosage, product, duration changes)
      2. Medical Document Generator produces amended authorization document
      3. Authorization Status API updates authorization with amended terms
    • if: revocation:
      1. Amendment & Revocation Engine records revocation reason under ss.137-139
      2. Authorization Status API sets patient status to expired immediately
      3. Checkout Gate blocks future purchases for this patient
  4. Patient receives notification of authorization change via Patient Dashboard
  5. Compliance Ledger records amendment or revocation event with full audit trail
  6. Licensing Notice Module sends templated notice under s.277 if required

Commerce & Fulfillment

Order lifecycle and Shopify integration after purchase

14. Shopify Order Status Sync Core

Order status and tracking data flows from Shopify to patient dashboard

flowchart TD
    A[Shopify updates order status] --> B[Order and Fulfillment Service detects change]
    B --> C[Updated order data stored in DB]
    C --> D[Patient opens Patient Dashboard]
    D --> E([Dashboard displays order status and tracking])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style E fill:#1a3a2a,stroke:#48bb78,color:#fff

Detailed Steps

  1. Shopify updates order status (confirmed, shipped, delivered)
  2. Order & Fulfillment Service detects status change from Shopify via API polling or webhook
  3. Order & Fulfillment Service stores updated order data in Application Database
  4. Patient opens Patient Dashboard and views current order status and tracking
  5. Patient Dashboard displays order history with fulfillment details from Shopify

Compliance & Regulatory

Verification, audit trail, and mandatory reporting under the Cannabis Act

11. Identity Verification (IDV) Extended Scope

Patient identity verified via third-party IDV provider during registration

flowchart TD
    A([Patient completes account creation]) --> B[IDV Integration initiates session]
    B --> C[Patient submits documents via IDV Provider]
    C --> D{IDV Provider result}
    D -->|Verified| E[Store verified status in DB]
    E --> F[Registration marked identity-confirmed]
    D -->|Failed| G[Store failure reason]
    G --> H([Patient prompted to retry])
    F --> I([Compliance Ledger records IDV result])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style D fill:#2d1b4e,stroke:#9f7aea,color:#fff
    style F fill:#1a3a2a,stroke:#48bb78,color:#fff
    style H fill:#742a2a,stroke:#fc8181,color:#fff

Detailed Steps

  1. Patient completes Account Creation Flow and is prompted for identity verification
  2. IDV Integration initiates verification session with IDV Provider
  3. Patient submits identity documents via IDV Provider widget
  4. IDV Provider processes documents and returns verification result
    • if: verified:
      1. IDV Integration stores verified status in Application Database
      2. Patient Registration Engine marks registration as identity-confirmed
    • if: failed:
      1. IDV Integration stores failure reason
      2. Patient is prompted to retry or contact support
  5. Compliance Ledger records IDV result in immutable audit trail

12. Practitioner License Verification Extended Scope

NP license verified against provincial college registry before case assignment

flowchart TD
    A[NP Workflow Service: pre-assignment check] --> B{Provincial College Registry lookup}
    B -->|License Active| C[Confirm validity, store result]
    C --> D[Proceed with case assignment]
    B -->|Not Found / Expired| E[Flag NP for manual review]
    E --> F[NP set to offline pending verification]
    B -->|Unsupported Province| G[Manual verification fallback]
    G --> H[Hold case assignment]
    D --> I([Compliance Ledger records verification])
    F --> I
    H --> I
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style B fill:#2d1b4e,stroke:#9f7aea,color:#fff
    style D fill:#1a3a2a,stroke:#48bb78,color:#fff
    style F fill:#3a2a1a,stroke:#ed8936,color:#fff

Detailed Steps

  1. NP Workflow Service prepares to assign case to Nurse Practitioner
  2. Practitioner License Verification queries Provincial College Registry for NP license status
    • if: license active:
      1. Practitioner License Verification confirms license validity and stores result
      2. NP Workflow Service proceeds with case assignment
    • if: license not found or expired:
      1. Practitioner License Verification flags NP for manual review
      2. NP Availability Management sets NP status to offline pending verification
    • if: unsupported province:
      1. Practitioner License Verification falls back to manual verification process
      2. NP Workflow Service holds case assignment until manual check completes
  3. Compliance Ledger records license verification event

9. Health Canada Monthly Reporting Regulatory

Automated monthly reports generated and submitted under s.297

flowchart TD
    A[Deadline scheduler triggers report] --> B[Query DB for reporting period events]
    B --> C[Aggregate data into s.297 format]
    C --> D[Submit report to Health Canada]
    D --> E[Health Canada acknowledges receipt]
    E --> F[Log submission confirmation in DB]
    F --> G([Compliance Ledger records submission])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style G fill:#1a3a2a,stroke:#48bb78,color:#fff

Detailed Steps

  1. Health Canada Reporter deadline scheduler triggers monthly report generation
  2. Health Canada Reporter queries Application Database for all authorization events in reporting period
  3. Health Canada Reporter aggregates data into s.297 report format
  4. Health Canada Reporter submits report to Health Canada
  5. Health Canada acknowledges receipt
  6. Health Canada Reporter logs submission confirmation in Application Database
  7. Compliance Ledger records report submission event with timestamp

10. Provincial Authority Disclosure Regulatory

Scoped disclosure packs submitted to provincial authorities under s.299

flowchart TD
    A[Identify disclosure obligation] --> B[Query DB for authorization records]
    B --> C[Assemble scoped disclosure pack: s.299]
    C --> D[Transmit via secure channel]
    D --> E[Log in secure transmission log]
    E --> F([Compliance Ledger records disclosure])
    style A fill:#1a365d,stroke:#3182ce,color:#fff
    style F fill:#1a3a2a,stroke:#48bb78,color:#fff

Detailed Steps

  1. Provincial Disclosure Module identifies disclosure obligation for a patient's province
  2. Provincial Disclosure Module queries Application Database for relevant authorization records
  3. Provincial Disclosure Module assembles scoped disclosure pack under s.299
  4. Provincial Disclosure Module transmits pack to Health Canada via secure channel
  5. Provincial Disclosure Module logs transmission in secure transmission log
  6. Compliance Ledger records disclosure event