Protocol Raw System Architecture

Layer 1: System Map

Version: 1.0
Status: Production Reference
Last Updated: January 2026
Owner: Protocol Raw Operations

---

1. Executive Summary

This document provides the complete architectural map of the Protocol Raw technical system. It shows how all components connect, what lives where, and how data flows from customer order to delivery confirmation.

Core Principle: Supabase is the integration spine. All data flows through PostgreSQL. External systems push data in; internal systems pull data out. The database is the single source of truth.

Scale Target: 100,000+ customers with zero manual intervention for routine operations.

---

2. System Architecture Diagram

flowchart TB
    subgraph EXT["EXTERNAL SYSTEMS"]
        SHOPIFY["Shopify<br/>(Orders)"]
        SEAL["Seal<br/>(Subscriptions)"]
        DPD["DPD<br/>(Courier)"]
        GMAIL["Gmail<br/>(Email)"]
    end

    subgraph INGEST["INGESTION LAYER"]
        SWH["shopify-webhook-handler<br/>(Edge Function)"]
        SEWH["seal-webhook-handler<br/>(Edge Function)"]
        MAKE["Make.com<br/>(DPD + Gmail watch)"]
    end

    SHOPIFY -->|Webhook| SWH
    SEAL -->|Webhook| SEWH
    DPD -->|Webhook| MAKE
    GMAIL -->|Watch| MAKE

    subgraph SUPA["SUPABASE (Integration Spine)"]
        subgraph DB["PostgreSQL (raw_ops schema)"]
            direction LR
            CORE["**Core Tables**<br/>customers · orders<br/>order_items · subscriptions"]
            OPS["**Operational Tables**<br/>batches · inventory<br/>allocations · shipments<br/>courier_events · lab_results"]
            SUPPORT["**Support Tables**<br/>support_tickets · ticket_messages<br/>cs_agent_decisions · kb_articles"]
            SYSTBL["**System Tables**<br/>webhook_inbox · ops_events<br/>monitoring_runs · email_outbox"]
        end
        PGCRON["pg_cron<br/>(Scheduling)"]
        TRIGGERS["Database Triggers<br/>(Real-time reactions)"]
        PGNET["pg_net<br/>(Async HTTP)"]
        subgraph EDGE["EDGE FUNCTIONS"]
            EF_ING["Ingestion<br/>shopify-webhook<br/>seal-webhook"]
            EF_PROC["Processing<br/>create-batch<br/>cs-agent-triage<br/>sync-address"]
            EF_MON["Monitoring<br/>run-monitor<br/>ops-alerter"]
            EF_COMMS["Comms<br/>send-support-email"]
        end
        DB --> PGCRON & TRIGGERS & PGNET
        PGCRON & TRIGGERS & PGNET --> EDGE
    end

    SWH & SEWH & MAKE --> DB

    subgraph OUTPUT["OUTPUT LAYER"]
        CIO["Customer.io<br/>(Email)"]
        SLACK["Slack<br/>(Alerts)"]
        META["Metabase<br/>(Analytics)"]
        subgraph UI["USER INTERFACES"]
            OPSPORTAL["Ops Portal<br/>ops.protocolraw.co.uk"]
            CUSTPORTAL["Customer Portal<br/>portal.protocolraw.co.uk"]
            PROOFPORTAL["Proof Portal<br/>proof.protocolraw.co.uk"]
        end
    end

    EDGE --> CIO & SLACK & META
    CIO & SLACK & META --> UI

    click SWH "https://docs.protocolraw.co.uk/sops/core/SOP_00_v4_0_FINAL/" "SOP-00: Shopify-Supabase Bridge"
    click SEWH "https://docs.protocolraw.co.uk/sops/subscriptions/SOP-SUB-00_Subscription_State_Management_v3_0_FINAL/" "SOP-SUB-00: Subscription State Management"
    click EF_PROC "https://docs.protocolraw.co.uk/sops/core/SOP_01_v4_3_FINAL/" "SOP-01: Batch Creation & Lab-to-Release"
    click EF_MON "https://docs.protocolraw.co.uk/sops/monitoring/SOP_MON_01_Monitoring_Alerting_Architecture_v1_0/" "SOP-MON-01: Monitoring Architecture"
    click OPSPORTAL "https://docs.protocolraw.co.uk/portals/Protocol_Raw_Operations_Portal_Documentation_v3_8/" "Operations Portal"
    click CUSTPORTAL "https://docs.protocolraw.co.uk/portals/Protocol_Raw_Customer_Portal_Documentation_v2_6_COMPLETE/" "Customer Portal"
    click PROOFPORTAL "https://docs.protocolraw.co.uk/sops/other/SOP-PROOF-01_Proof_Portal_System_v1_0/" "SOP-PROOF-01: Proof Portal"

---

3. Data Flow Diagrams

3.1 Order Lifecycle Flow

flowchart TD
    A["🛒 Shopify<br/>Customer places order"] -->|orders/create webhook| B["shopify-webhook-handler<br/>(Edge Function)<br/>Validates HMAC, stores in webhook_inbox"]
    B -->|process_order_webhook_txn| C["Supabase Database<br/>1. Upsert customer<br/>2. Create order<br/>3. Create order_items<br/>4. Log ops_event"]
    C -->|"trg_allocate_on_order"| D["Auto-Allocation<br/>FEFO selection from RELEASED batches<br/>Create allocation · Decrement inventory"]
    D -->|"Status: ALLOCATED"| E["Order Export<br/>pg_cron daily job → CSV generation"]
    E -->|"CSV to 3PL"| F["Pack Day<br/>Pick list · QC checks · PCM · Packing"]
    F -->|"Ops Portal: Record dispatch"| G["Dispatch<br/>Tracking # · Shipment · Courier submission"]
    G -->|"DPD webhook"| H["Courier Tracking<br/>Make.com receives events<br/>Exception detection · Notifications"]
    H -->|"Final delivery event"| I["✅ Delivered<br/>Shipment status = delivered<br/>Confirmation email via Customer.io"]

    click B "https://docs.protocolraw.co.uk/sops/core/SOP_00_v4_0_FINAL/" "SOP-00: Shopify-Supabase Bridge"
    click D "https://docs.protocolraw.co.uk/sops/core/SOP_01_v4_3_FINAL/" "SOP-01: Batch Creation & Allocation"
    click E "https://docs.protocolraw.co.uk/sops/core/SOP_0X_v3_0_FINAL__1_/" "SOP-0X: 3PL Order Export"
    click F "https://docs.protocolraw.co.uk/sops/packing/SOP-PACK-01_Intelligent_Packing_Operations_v2_0_FINAL/" "SOP-PACK-01: Intelligent Packing Operations"
    click G "https://docs.protocolraw.co.uk/sops/core/SOP_0Y_v2_0_FINAL/" "SOP-0Y: Dispatch Confirmation"

3.2 Batch Lifecycle Flow

flowchart TD
    A["📦 Co-Packer Confirms Production<br/>Email/call: 500kg produced today"] -->|"Ops Portal: Batch Creation tab"| B["Batch Creation<br/>Enter date + kg → auto-generates<br/>batch code · public ID · QR · label PDF"]
    B -->|"Email: Label PDF to co-packer"| C["QA_HOLD<br/>Batch awaiting lab results<br/>Inventory on hold · Cannot allocate"]
    C -->|"Lab sends results (2-5 days)"| D["Lab Processing<br/>Gmail watch → Extract PDF<br/>GPT-4o Vision parses → Store results"]
    D -->|"All tests PASS?"| E{"Batch Release"}
    E -->|"✅ All pass"| F["RELEASED<br/>Inventory released<br/>Proof portal updated"]
    E -->|"❌ Any fail"| G["FAILED<br/>Alert to #ops-urgent<br/>Manual investigation"]
    F -->|"trg_allocate_pending_on_release"| H["Auto-Allocation<br/>FEFO allocation for pending orders<br/>Decrement inventory"]
    H -->|"Customer scans QR"| I["Proof Portal<br/>Production date · Batch codes<br/>Lab results · PASS/FAIL"]

    click B "https://docs.protocolraw.co.uk/sops/core/SOP_01_v4_3_FINAL/" "SOP-01: Batch Creation & Lab-to-Release"
    click D "https://docs.protocolraw.co.uk/sops/core/SOP_01_v4_3_FINAL/" "SOP-01: Lab Processing"
    click C "https://docs.protocolraw.co.uk/sops/monitoring/SOP_MON_01_Monitoring_Alerting_Architecture_v1_0/" "SOP-MON-01: Monitoring"
    click I "https://docs.protocolraw.co.uk/sops/other/SOP-PROOF-01_Proof_Portal_System_v1_0/" "SOP-PROOF-01: Proof Portal"
    click F "https://docs.protocolraw.co.uk/sops/core/SOP_0R_v4_2_FINAL/" "SOP-0R: Proof-of-Safety System"

3.3 Support Ticket Flow

flowchart TD
    A["Customer Email<br/>support@protocolraw.co.uk"] -->|"Make.com: Gmail inbox watch"| B["CS-01: Email Triage<br/>Extract body · Capture Message-ID<br/>Call cs-agent-triage Edge Function"]
    B -->|"Edge Function processing"| C["AI Classification<br/>1. Preflight policy gates<br/>2. Customer context retrieval<br/>3. KB search — pgvector<br/>4. Claude API classification<br/>5. Store decision"]
    C -->|"Confidence >= 85% + No gate"| D["Shadow Mode<br/>Draft queued for review<br/>Human approves"]
    C -->|"Confidence < 85% OR Gate triggered"| E["Escalation<br/>Status = escalated<br/>Alert to #ops-urgent"]
    D --> F["Agent Review Tab<br/>(Ops Portal)<br/>View draft · Edit · Approve/Reject"]
    E --> G["Support Workstation<br/>(Ops Portal)<br/>Full context · Manual response"]
    F --> H["Email Delivery<br/>Customer.io Transactional API<br/>Threading · Logged to ticket_messages"]
    G --> H

    click B "https://docs.protocolraw.co.uk/sops/customer-ops/SOP_CS_01_AI_Customer_Service_Triage_v2_1/" "SOP-CS-01: AI Customer Service Triage"
    click C "https://docs.protocolraw.co.uk/sops/customer-ops/SOP_CS_03_v1_5_PRODUCTION_READY/" "SOP-CS-03: Autonomous Support Agent"
    click D "https://docs.protocolraw.co.uk/sops/customer-ops/SOP_CS_03_v1_5_PRODUCTION_READY/" "SOP-CS-03: Shadow Mode"
    click F "https://docs.protocolraw.co.uk/portals/Protocol_Raw_Operations_Portal_Documentation_v3_8/" "Operations Portal"
    click G "https://docs.protocolraw.co.uk/sops/customer-ops/SOP_CS_02_Live_Chat_System_v1_8_PRODUCTION_READY/" "SOP-CS-02: Live Chat System"
    click H "https://docs.protocolraw.co.uk/sops/customer-ops/SOP_CS_05_CSAT_Survey_System_v1_0/" "SOP-CS-05: CSAT Survey"

3.4 Monitoring & Alerting Flow

flowchart TD
    A["pg_cron (Supabase native)<br/>Scheduled job execution"] --> B["run-monitor<br/>(Edge Function)<br/>Receives check name · Calls fn_check_*_v2()"]
    B --> C["PostgreSQL Function<br/>fn_check_*_v2()<br/>Run check · Evaluate thresholds<br/>Log to monitoring_runs"]
    C -->|"Threshold OK"| D["No Action<br/>Run logged · Silence = healthy"]
    C -->|"Threshold Breached"| E["ops-alerter<br/>(Edge Function)<br/>Format message · Route to channel"]
    E --> F["Slack<br/>#ops-alerts — Warning<br/>#ops-urgent — Critical<br/>#daily-ops — Info/Digest"]

    A -.- G["**Scheduled Checks**<br/>Order ingestion SLO (2 min)<br/>Outbox health (5 min)<br/>Stock levels (15 min)<br/>Lab SLA (15 min)<br/>Working capital (daily 08:00)<br/>Daily snapshot (daily 09:00)<br/>Support queue (15 min)"]

    click A "https://docs.protocolraw.co.uk/sops/monitoring/SOP_MON_01_Monitoring_Alerting_Architecture_v1_0/" "SOP-MON-01: Monitoring & Alerting Architecture"
    click B "https://docs.protocolraw.co.uk/sops/monitoring/SOP-MON-02_Order_Ingestion_SLO_Monitor_v2_0/" "SOP-MON-02: Order Ingestion SLO Monitor"
    click E "https://docs.protocolraw.co.uk/sops/monitoring/SOP-MON-03_Allocation_Health_Monitor_v1_0/" "SOP-MON-03: Allocation Health Monitor"
    click C "https://docs.protocolraw.co.uk/sops/core/SOP_03_v3_1_PRODUCTION_READY/" "SOP-03: Daily Snapshot Ping"

---

4. System Boundaries

4.1 What Lives Where

Layer	Technology	Purpose
Database	Supabase PostgreSQL	Single source of truth for all data
Schema	raw_ops	All operational tables, views, functions
Compute (Scheduled)	pg_cron	All scheduled operations
Compute (Async)	pg_net	Internal HTTP calls to Edge Functions
Compute (Logic)	PostgreSQL Functions	Business logic, data transformation
Compute (External APIs)	Edge Functions	All external API calls
Orchestration	Make.com	Multi-system coordination only
Email	Customer.io	All customer communications
Alerts	Slack	Operational notifications
Analytics	Metabase	Dashboards and reporting
Ops Interface	Ops Portal (Cloudflare)	Internal team operations
Customer Interface	Customer Portal (Cloudflare)	Customer self-service
Verification	Proof Portal (Cloudflare)	Public batch verification

4.2 Decision Rules

Scenario	Use This	Not This	Reason
Scheduled check every N minutes	pg_cron + pg_net + Edge Function	Make.com scheduler	Native stack, no external dependency
React to database change	Database trigger + pg_net	Make.com webhook	Real-time, no polling
Call single external API	Edge Function	Make.com	Simpler, faster, cheaper
Coordinate 3+ external systems	Make.com	Edge Function	Visual debugging, error handling
Store data	PostgreSQL	Edge Function memory	Persistence, queryability
Complex data transformation	PostgreSQL function	Edge Function	SQL is purpose-built for this
Send email	Customer.io via Edge Function	Direct SMTP	Deliverability, analytics
Send alert	ops-alerter Edge Function	Direct Slack API	Centralized, formatted

---

5. Integration Points Summary

5.1 Inbound Data Flows

Source	Destination	Method	Data
Shopify	webhook_inbox → orders	Webhook → Edge Function	Orders, customers
Seal	subscription_events → subscriptions	Webhook → Edge Function	Subscription state changes
DPD	courier_events	Webhook → Make.com	Tracking events
Gmail	support_tickets	Watch → Make.com	Support emails
Gmail	lab_results	Watch → Make.com	Lab result PDFs
Lab	lab_results	Email → OpenAI → Make.com	Test results

5.2 Outbound Data Flows

Source	Destination	Method	Data
Database trigger	Customer.io	Edge Function → API	Lifecycle events
Ops Portal	Customer.io	Edge Function → API	Support responses
Monitoring	Slack	Edge Function → Webhook	Alerts
Support agent	Customer inbox	Edge Function → Customer.io	Email replies
Batch creation	Co-packer email	Edge Function → Resend	Label PDFs
Database	Metabase	Direct SQL	Analytics queries
Database	Ops Portal	Supabase REST API	Operational data
Database	Customer Portal	Supabase REST API	Customer data

---

6. Related Documentation

Document	Purpose
Layer 2: Component Registry	Complete specification of all tables, functions, Edge Functions
Layer 3: Integration Specifications	Detailed API specs for all external systems
Layer 4: SOP Cross-Reference	Master index of all SOPs and their relationships

---

Protocol Raw — Verified safe, batch by batch.