# arsalanqasim/cod-guard architecture

> Architecture diagram of the GitHub repository arsalanqasim/cod-guard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arsalanqasim/cod-guard
- Repository: https://github.com/arsalanqasim/cod-guard

## Overview

COD-Guard is a local COD-order risk and verification demo, with an optional authenticated shadow-intake API. The main user workflow is to review an order queue and risk assessment, verify a customer reply (including Urdu voice transcription), record the delivery outcome, and inspect or retrain from marked outcomes. Separate branches cover storefront/social intake, WhatsApp messaging, public benchmark and savings metrics, and consent-scoped reputation counts. The dashboard and API share transactional SQLite state. The README documents capabilities beyond the sampled excerpts; their internal wiring is shown only where the README or source index supports it.

Main entry points: [`frontend/dashboard.py`](https://github.com/arsalanqasim/cod-guard/blob/main/frontend/dashboard.py) (Demo dashboard), [`backend/app/main.py`](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/main.py) (HTTP API), [`backend/app/service.py`](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/service.py) (Order queue), [`backend/app/risk_engine.py`](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/risk_engine.py) (Risk policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Operator experience"]
  node_dashboard["Demo dashboard<br/>[dashboard.py]"]
  node_api["HTTP API<br/>[main.py]"]
  node_orders["Order queue<br/>[service.py]"]
  node_whatsapp_routes["WhatsApp routes<br/>[whatsapp_routes.py]"]
  node_whatsapp_cloud["WhatsApp Cloud<br/>[whatsapp_cloud.py]"]
  node_network_routes["Network routes<br/>[network_routes.py]"]
end

subgraph group_decision["Risk and verification"]
  node_risk["Risk policy<br/>[risk_engine.py]"]
  node_verification["Reply verification<br/>[verification.py]"]
  node_voice["Urdu voice transcription<br/>[verification.py]"]
end

subgraph group_intake["Order intake"]
  node_intake_core["Order intake<br/>[order_intake.py]"]
  node_storefront_sync["Storefront reconciliation"]
  node_woocommerce["WooCommerce connector<br/>[woocommerce.py]"]
  node_shopify["Shopify intake<br/>[shopify_routes.py]"]
  node_daraz["Daraz connector<br/>[daraz.py]"]
  node_social["Social intake<br/>[social_routes.py]"]
end

subgraph group_learning["Learning and metrics"]
  node_outcomes["Courier outcomes"]
  node_training["Model training<br/>[train_model.py]"]
  node_evaluation["Evaluation"]
  node_benchmark["Public benchmark"]
  node_savings["Savings report<br/>[savings_report.py]"]
end

subgraph group_state["State and network"]
  node_storage[("Transactional state<br/>[storage.py]")]
  node_records[("SQLite records<br/>[records.py]")]
  node_network[("Reputation network")]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_dashboard
node_operator -->|"uses"| node_api
node_dashboard -->|"loads queue"| node_orders
node_orders -->|"assesses orders"| node_risk
node_orders -->|"applies replies"| node_verification
node_dashboard -->|"transcribes notes"| node_voice
node_dashboard -->|"applies transcript"| node_verification
node_api -->|"routes intake"| node_intake_core
node_intake_core -->|"assesses orders"| node_risk
node_api -->|"registers routes"| node_woocommerce
node_woocommerce -->|"normalizes orders"| node_storefront_sync
node_api -->|"registers routes"| node_shopify
node_shopify -->|"reconciles snapshots"| node_storefront_sync
node_api -->|"registers routes"| node_social
node_api -->|"registers routes"| node_whatsapp_routes
node_whatsapp_routes -->|"sends verification"| node_whatsapp_cloud
node_dashboard -->|"marks outcomes"| node_outcomes
node_outcomes -->|"updates contributions"| node_network
node_dashboard -->|"requests retraining"| node_training
node_training -->|"evaluates policy"| node_risk
node_dashboard -->|"shows metrics"| node_benchmark
node_dashboard -->|"shows savings"| node_savings
node_orders -->|"reads state"| node_storage
node_storage -->|"persists records"| node_records
node_api -->|"registers routes"| node_network_routes
node_network_routes -->|"queries counts"| node_network
node_api -.->|"optional connector"| node_daraz
node_dashboard -.->|"shows evaluation"| node_evaluation

click node_dashboard "https://github.com/arsalanqasim/cod-guard/blob/main/frontend/dashboard.py"
click node_api "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/main.py"
click node_orders "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/service.py"
click node_risk "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/risk_engine.py"
click node_verification "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/verification.py"
click node_voice "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/verification.py"
click node_intake_core "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/order_intake.py"
click node_storefront_sync "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/connector_orders.py"
click node_woocommerce "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/woocommerce.py"
click node_shopify "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/shopify_routes.py"
click node_daraz "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/daraz.py"
click node_social "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/social_routes.py"
click node_whatsapp_routes "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/whatsapp_routes.py"
click node_whatsapp_cloud "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/whatsapp_cloud.py"
click node_outcomes "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/courier_outcomes.py"
click node_training "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/train_model.py"
click node_evaluation "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/round2_evaluation.py"
click node_benchmark "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/public_benchmark.py"
click node_savings "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/savings_report.py"
click node_storage "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/storage.py"
click node_records "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/records.py"
click node_network "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/reputation_network.py"
click node_network_routes "https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/network_routes.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_api,node_orders,node_whatsapp_routes,node_whatsapp_cloud,node_network_routes toneBlue
class node_risk,node_verification,node_voice toneAmber
class node_intake_core,node_storefront_sync,node_woocommerce,node_shopify,node_daraz,node_social toneMint
class node_outcomes,node_training,node_evaluation,node_benchmark,node_savings toneRose
class node_storage,node_records,node_network,node_operator toneIndigo
```

## Components

### Operator experience

- [Demo dashboard](https://github.com/arsalanqasim/cod-guard/blob/main/frontend/dashboard.py): `frontend/dashboard.py`
- [HTTP API](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/main.py): `backend/app/main.py`
- [Order queue](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/service.py): `backend/app/service.py`
- [WhatsApp routes](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/whatsapp_routes.py): `backend/app/whatsapp_routes.py`
- [WhatsApp Cloud](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/whatsapp_cloud.py): `backend/app/whatsapp_cloud.py`
- [Network routes](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/network_routes.py): `backend/app/network_routes.py`

### Risk and verification

- [Risk policy](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/risk_engine.py): `backend/app/risk_engine.py`
- [Reply verification](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/verification.py): `backend/app/verification.py`
- [Urdu voice transcription](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/verification.py): `backend/app/verification.py`

### Order intake

- [Order intake](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/order_intake.py): `backend/app/order_intake.py`
- [Storefront reconciliation](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/connector_orders.py): `backend/app/connector_orders.py`
- [WooCommerce connector](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/woocommerce.py): `backend/app/woocommerce.py`
- [Shopify intake](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/shopify_routes.py): `backend/app/shopify_routes.py`
- [Daraz connector](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/daraz.py): `backend/app/daraz.py`
- [Social intake](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/social_routes.py): `backend/app/social_routes.py`

### Learning and metrics

- [Courier outcomes](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/courier_outcomes.py): `backend/app/courier_outcomes.py`
- [Model training](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/train_model.py): `backend/app/train_model.py`
- [Evaluation](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/round2_evaluation.py): `backend/app/round2_evaluation.py`
- [Public benchmark](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/public_benchmark.py): `backend/app/public_benchmark.py`
- [Savings report](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/savings_report.py): `backend/app/savings_report.py`

### State and network

- [Transactional state](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/storage.py): `backend/app/storage.py`
- [SQLite records](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/records.py): `backend/app/records.py`
- [Reputation network](https://github.com/arsalanqasim/cod-guard/blob/main/backend/app/reputation_network.py): `backend/app/reputation_network.py`

### Other components

- **Operator**

## Connections

- Operator → Demo dashboard: uses
- Operator → HTTP API: uses
- Demo dashboard → Order queue: loads queue (evidence: `frontend/dashboard.py`)
- Order queue → Risk policy: assesses orders (evidence: `backend/app/service.py`)
- Order queue → Reply verification: applies replies (evidence: `backend/app/service.py`)
- Demo dashboard → Urdu voice transcription: transcribes notes (evidence: `frontend/dashboard.py`)
- Demo dashboard → Reply verification: applies transcript (evidence: `frontend/dashboard.py`)
- HTTP API → Order intake: routes intake (evidence: `backend/app/main.py`)
- Order intake → Risk policy: assesses orders (evidence: `backend/app/order_intake.py`)
- HTTP API → WooCommerce connector: registers routes (evidence: `backend/app/main.py`)
- WooCommerce connector → Storefront reconciliation: normalizes orders (evidence: `backend/app/woocommerce.py`)
- HTTP API → Shopify intake: registers routes (evidence: `backend/app/main.py`)
- Shopify intake → Storefront reconciliation: reconciles snapshots (evidence: `backend/app/shopify_routes.py`)
- HTTP API → Social intake: registers routes (evidence: `backend/app/main.py`)
- HTTP API → WhatsApp routes: registers routes (evidence: `backend/app/main.py`)
- WhatsApp routes → WhatsApp Cloud: sends verification (evidence: `backend/app/whatsapp_routes.py`)
- Demo dashboard → Courier outcomes: marks outcomes
- Courier outcomes → Reputation network: updates contributions (evidence: `backend/app/courier_outcomes.py`)
- Demo dashboard → Model training: requests retraining
- Model training → Risk policy: evaluates policy (evidence: `backend/app/train_model.py`)
- Demo dashboard → Public benchmark: shows metrics (evidence: `frontend/dashboard.py`)
- Demo dashboard → Savings report: shows savings (evidence: `frontend/dashboard.py`)
- Order queue → Transactional state: reads state (evidence: `backend/app/service.py`)
- Transactional state → SQLite records: persists records (evidence: `backend/app/storage.py`)
- HTTP API → Network routes: registers routes (evidence: `backend/app/main.py`)
- Network routes → Reputation network: queries counts (evidence: `backend/app/network_routes.py`)
- HTTP API → Daraz connector: optional connector
- Demo dashboard → Evaluation: shows evaluation
