# grizzy100/callzo-usage-metering architecture

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

- Interactive diagram: https://gitdiagram.com/grizzy100/callzo-usage-metering
- Repository: https://github.com/grizzy100/callzo-usage-metering

## Overview

Callzo combines a webhook-driven usage metering API with a browser-based usage admin console. Telephony events enter the API, are validated and stored, then processed into call and monthly usage records; authenticated account and usage endpoints expose data to the console, which presents overview analytics, account search/management, and settings. Retry and reconciliation are distinct operational stages. Backend service wiring beyond the excerpts is limited to references in the source index; the repository-level README describes the two tasks but not their detailed runtime relationships.

Main entry points: [`server/src/config/db.js`](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/config/db.js) (PostgreSQL data), [`client/src/App.jsx`](https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/App.jsx) (Console shell), [`server/src/server.js`](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/server.js) (Express API), [`server/src/routes/webhook.routes.js`](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/routes/webhook.routes.js) (Webhook route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Admin console"]
  node_console["Console shell<br/>[App.jsx]"]
  node_navigation["Navigation and header<br/>[Sidebar.jsx]"]
  node_overview["Usage overview<br/>[Overview.jsx]"]
  node_accounts["Account management<br/>[Accounts.jsx]"]
  node_settings["Account settings"]
  node_chart["Usage chart<br/>[UsageChart.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and access"]
  node_api_server["Express API<br/>[server.js]"]
  node_auth_routes["Authentication routes<br/>[auth.routes.js]"]
  node_auth_controller["Authentication<br/>[auth.controller.js]"]
  node_account_routes["Account routes<br/>[account.routes.js]"]
  node_account_controller["Account listing"]
  node_usage_controller["Account usage"]
  node_webhook_routes["Webhook route<br/>[webhook.routes.js]"]
  node_signature["Signature verification"]
  node_webhook_controller["Webhook intake"]
end

subgraph group_events["Event metering"]
  node_webhook_service["Event persistence<br/>[webhook.service.js]"]
  node_event_processor["Call event processing"]
  node_database[("PostgreSQL data<br/>[db.js]")]
end

subgraph group_operations["Usage operations"]
  node_retry_worker["Retry worker<br/>[retry.worker.js]"]
  node_retry_service["Retry processing<br/>[retry.service.js]"]
  node_reconciliation["Usage reconciliation"]
end

node_user(("Admin user"))
node_telephony(("Telephony provider"))

node_user -->|"uses"| node_console
node_console -->|"renders"| node_navigation
node_console -->|"selects view"| node_overview
node_console -->|"selects view"| node_accounts
node_console -->|"selects view"| node_settings
node_overview -->|"renders"| node_chart
node_overview -->|"requests data"| node_api_client
node_accounts -->|"renders"| node_chart
node_accounts -->|"requests data"| node_api_client
node_settings -->|"requests settings"| node_api_client
node_api_client -.->|"HTTP requests"| node_api_server
node_api_server -->|"mounts"| node_auth_routes
node_api_server -->|"mounts"| node_account_routes
node_api_server -->|"mounts"| node_webhook_routes
node_auth_routes -->|"routes to"| node_auth_controller
node_account_routes -->|"routes to"| node_account_controller
node_account_routes -->|"routes to"| node_usage_controller
node_account_controller -->|"queries"| node_database
node_usage_controller -->|"queries"| node_database
node_telephony -.->|"sends events"| node_webhook_routes
node_webhook_routes -->|"verifies"| node_signature
node_webhook_routes -->|"dispatches"| node_webhook_controller
node_webhook_controller -->|"stores event"| node_webhook_service
node_webhook_service -.->|"writes event"| node_database
node_event_processor -->|"updates calls and usage"| node_database
node_retry_worker -->|"runs retries"| node_retry_service
node_retry_service -.->|"reprocesses events"| node_event_processor
node_retry_service -.->|"reads retry state"| node_database
node_reconciliation -.->|"reconciles events"| node_event_processor
node_reconciliation -.->|"checks records"| node_database

click node_console "https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/App.jsx"
click node_navigation "https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/components/Sidebar.jsx"
click node_overview "https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/pages/Overview.jsx"
click node_accounts "https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/pages/Accounts.jsx"
click node_settings "https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/pages/AccountSettings.jsx"
click node_chart "https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/components/UsageChart.jsx"
click node_api_client "https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/services/api.js"
click node_api_server "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/server.js"
click node_auth_routes "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/routes/auth.routes.js"
click node_auth_controller "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/controllers/auth.controller.js"
click node_account_routes "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/routes/account.routes.js"
click node_account_controller "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/controllers/account.controller.js"
click node_usage_controller "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/controllers/usage.controller.js"
click node_webhook_routes "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/routes/webhook.routes.js"
click node_signature "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/middleware/signature.middleware.js"
click node_webhook_controller "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/controllers/webhook.controller.js"
click node_webhook_service "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/services/webhook.service.js"
click node_event_processor "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/services/event-processing.service.js"
click node_database "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/config/db.js"
click node_retry_worker "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/workers/retry.worker.js"
click node_retry_service "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/services/retry.service.js"
click node_reconciliation "https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/services/reconciliation.service.js"

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_console,node_navigation,node_overview,node_accounts,node_settings,node_chart,node_api_client,node_user toneBlue
class node_api_server,node_auth_routes,node_auth_controller,node_account_routes,node_account_controller,node_usage_controller,node_webhook_routes,node_signature,node_webhook_controller toneAmber
class node_webhook_service,node_event_processor,node_database toneMint
class node_retry_worker,node_retry_service,node_reconciliation toneRose
class node_telephony toneIndigo
```

## Components

### Admin console

- [Console shell](https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Navigation and header](https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/components/Sidebar.jsx): `client/src/components/Sidebar.jsx`
- [Usage overview](https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/pages/Overview.jsx): `client/src/pages/Overview.jsx`
- [Account management](https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/pages/Accounts.jsx): `client/src/pages/Accounts.jsx`
- [Account settings](https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/pages/AccountSettings.jsx): `client/src/pages/AccountSettings.jsx`
- [Usage chart](https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/components/UsageChart.jsx): `client/src/components/UsageChart.jsx`
- [API client](https://github.com/grizzy100/callzo-usage-metering/blob/main/client/src/services/api.js): `client/src/services/api.js`

### API and access

- [Express API](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/server.js): `server/src/server.js`
- [Authentication routes](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/routes/auth.routes.js): `server/src/routes/auth.routes.js`
- [Authentication](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/controllers/auth.controller.js): `server/src/controllers/auth.controller.js`
- [Account routes](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/routes/account.routes.js): `server/src/routes/account.routes.js`
- [Account listing](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/controllers/account.controller.js): `server/src/controllers/account.controller.js`
- [Account usage](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/controllers/usage.controller.js): `server/src/controllers/usage.controller.js`
- [Webhook route](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/routes/webhook.routes.js): `server/src/routes/webhook.routes.js`
- [Signature verification](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/middleware/signature.middleware.js): `server/src/middleware/signature.middleware.js`
- [Webhook intake](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/controllers/webhook.controller.js): `server/src/controllers/webhook.controller.js`

### Event metering

- [Event persistence](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/services/webhook.service.js): `server/src/services/webhook.service.js`
- [Call event processing](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/services/event-processing.service.js): `server/src/services/event-processing.service.js`
- [PostgreSQL data](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/config/db.js): `server/src/config/db.js`

### Usage operations

- [Retry worker](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/workers/retry.worker.js): `server/src/workers/retry.worker.js`
- [Retry processing](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/services/retry.service.js): `server/src/services/retry.service.js`
- [Usage reconciliation](https://github.com/grizzy100/callzo-usage-metering/blob/main/server/src/services/reconciliation.service.js): `server/src/services/reconciliation.service.js`

### Other components

- **Admin user**
- **Telephony provider**

## Connections

- Admin user → Console shell: uses (evidence: `client/src/App.jsx`)
- Console shell → Navigation and header: renders (evidence: `client/src/App.jsx`)
- Console shell → Usage overview: selects view (evidence: `client/src/App.jsx`)
- Console shell → Account management: selects view (evidence: `client/src/App.jsx`)
- Console shell → Account settings: selects view (evidence: `client/src/App.jsx`)
- Usage overview → Usage chart: renders (evidence: `client/src/pages/Overview.jsx`)
- Usage overview → API client: requests data (evidence: `client/src/pages/Overview.jsx`)
- Account management → Usage chart: renders (evidence: `client/src/pages/Accounts.jsx`)
- Account management → API client: requests data (evidence: `client/src/pages/Accounts.jsx`)
- Account settings → API client: requests settings (evidence: `client/src/pages/AccountSettings.jsx`)
- API client → Express API: HTTP requests
- Express API → Authentication routes: mounts (evidence: `server/src/server.js`)
- Express API → Account routes: mounts (evidence: `server/src/server.js`)
- Express API → Webhook route: mounts (evidence: `server/src/server.js`)
- Authentication routes → Authentication: routes to (evidence: `server/src/routes/auth.routes.js`)
- Account routes → Account listing: routes to (evidence: `server/src/routes/account.routes.js`)
- Account routes → Account usage: routes to (evidence: `server/src/routes/account.routes.js`)
- Account listing → PostgreSQL data: queries (evidence: `server/src/controllers/account.controller.js`)
- Account usage → PostgreSQL data: queries (evidence: `server/src/controllers/usage.controller.js`)
- Telephony provider → Webhook route: sends events
- Webhook route → Signature verification: verifies (evidence: `server/src/routes/webhook.routes.js`)
- Webhook route → Webhook intake: dispatches (evidence: `server/src/routes/webhook.routes.js`)
- Webhook intake → Event persistence: stores event (evidence: `server/src/controllers/webhook.controller.js`)
- Event persistence → PostgreSQL data: writes event (evidence: `server/src/services/webhook.service.js`)
- Call event processing → PostgreSQL data: updates calls and usage (evidence: `server/src/services/event-processing.service.js`)
- Retry worker → Retry processing: runs retries (evidence: `server/src/workers/retry.worker.js`)
- Retry processing → Call event processing: reprocesses events (evidence: `server/src/services/retry.service.js`)
- Retry processing → PostgreSQL data: reads retry state (evidence: `server/src/services/retry.service.js`)
- Usage reconciliation → Call event processing: reconciles events (evidence: `server/src/services/reconciliation.service.js`)
- Usage reconciliation → PostgreSQL data: checks records (evidence: `server/src/services/reconciliation.service.js`)
