# gsarankumar29/gcp-sre-voice-dispatcher architecture

> Architecture diagram of the GitHub repository gsarankumar29/gcp-sre-voice-dispatcher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gsarankumar29/gcp-sre-voice-dispatcher
- Repository: https://github.com/gsarankumar29/gcp-sre-voice-dispatcher

## Overview

GCP SRE Voice Dispatcher receives Cloud Run incident alerts through Pub/Sub or a direct webhook, validates and filters them, then simulates or requests a Vapi voice call. During calls, Vapi can invoke tools to acknowledge an incident or retry an allowed Cloud Run job. Configuration and token verification support these flows. The README documents the cloud delivery and voice integrations; source excerpts show the application-side handlers. Acknowledgement is currently temporary and non-persistent.

Main entry points: [`app/main.py`](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/main.py) (FastAPI Dispatcher), [`app/services/vapi_service.py`](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/services/vapi_service.py) (Voice Dispatch Service), [`app/api/vapi_tools.py`](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/api/vapi_tools.py) (Tool Dispatch), [`app/services/cloud_run_service.py`](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/services/cloud_run_service.py) (Cloud Run Job Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Alert Ingestion"]
  node_dispatcher["FastAPI Dispatcher<br/>[main.py]"]
  node_alert_payload["Alert Payload Model<br/>[alerts.py]"]
  node_severity_filter["Severity Filter<br/>[main.py]"]
end

subgraph group_dispatch["Incident Dispatch"]
  node_vapi_service["Voice Dispatch Service<br/>[vapi_service.py]"]
  node_simulation["Simulation Mode<br/>[vapi_service.py]"]
end

subgraph group_tools["Voice Tools"]
  node_tools_endpoint["Vapi Tools Endpoint<br/>[vapi_tools.py]"]
  node_tool_router["Tool Dispatch<br/>[vapi_tools.py]"]
  node_acknowledgement["Incident Acknowledgement<br/>[vapi_tools.py]"]
  node_cloud_run_service["Cloud Run Job Service"]
end

subgraph group_support["Security And Config"]
  node_auth["Token Verification<br/>[auth.py]"]
  node_settings["Application Settings<br/>[config.py]"]
end

node_run_failure["Cloud Run Failure"]
node_gcp_alert["Google Cloud Alert"]
node_pubsub_topic["Pub/Sub Topic"]
node_push_subscription["Push Subscription"]
node_direct_alert(("Direct Alert Sender"))
node_vapi_api["Vapi API"]
node_engineer(("On-Call Engineer"))
node_vapi_assistant(("Vapi Assistant"))
node_cloud_run_jobs["Cloud Run Jobs"]

node_run_failure -.->|"raises alert"| node_gcp_alert
node_gcp_alert -.->|"publishes alert"| node_pubsub_topic
node_pubsub_topic -.->|"delivers messages"| node_push_subscription
node_push_subscription -.->|"posts alerts"| node_dispatcher
node_direct_alert -.->|"posts alert"| node_dispatcher
node_dispatcher -->|"validates payload"| node_alert_payload
node_dispatcher -->|"requires token check"| node_auth
node_auth -->|"checks configured token"| node_settings
node_dispatcher -->|"checks severity"| node_severity_filter
node_dispatcher -->|"requests dispatch"| node_vapi_service
node_vapi_service -->|"reads dispatch settings"| node_settings
node_vapi_service -->|"selects simulation"| node_simulation
node_vapi_service -->|"requests outbound call"| node_vapi_api
node_vapi_api -.->|"places voice call"| node_engineer
node_vapi_assistant -.->|"calls tool webhook"| node_tools_endpoint
node_tools_endpoint -->|"dispatches tool calls"| node_tool_router
node_tool_router -->|"handles acknowledge"| node_acknowledgement
node_tool_router -->|"requests job retry"| node_cloud_run_service
node_cloud_run_service -->|"reads job configuration"| node_settings
node_cloud_run_service -->|"starts job execution"| node_cloud_run_jobs

click node_dispatcher "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/main.py"
click node_alert_payload "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/models/alerts.py"
click node_severity_filter "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/main.py"
click node_auth "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/security/auth.py"
click node_settings "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/config.py"
click node_vapi_service "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/services/vapi_service.py"
click node_simulation "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/services/vapi_service.py"
click node_tools_endpoint "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/api/vapi_tools.py"
click node_tool_router "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/api/vapi_tools.py"
click node_acknowledgement "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/api/vapi_tools.py"
click node_cloud_run_service "https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/services/cloud_run_service.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_dispatcher,node_alert_payload,node_severity_filter toneBlue
class node_vapi_service,node_simulation toneAmber
class node_tools_endpoint,node_tool_router,node_acknowledgement,node_cloud_run_service,node_vapi_api,node_vapi_assistant toneMint
class node_auth,node_settings toneRose
class node_run_failure,node_gcp_alert,node_pubsub_topic,node_push_subscription,node_direct_alert,node_engineer,node_cloud_run_jobs toneIndigo
```

## Components

### Alert Ingestion

- [FastAPI Dispatcher](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/main.py): `app/main.py`
- [Alert Payload Model](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/models/alerts.py): `app/models/alerts.py`
- [Severity Filter](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/main.py): `app/main.py`

### Incident Dispatch

- [Voice Dispatch Service](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/services/vapi_service.py): `app/services/vapi_service.py`
- [Simulation Mode](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/services/vapi_service.py): `app/services/vapi_service.py`

### Voice Tools

- [Vapi Tools Endpoint](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/api/vapi_tools.py): `app/api/vapi_tools.py`
- [Tool Dispatch](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/api/vapi_tools.py): `app/api/vapi_tools.py`
- [Incident Acknowledgement](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/api/vapi_tools.py): `app/api/vapi_tools.py`
- [Cloud Run Job Service](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/services/cloud_run_service.py): `app/services/cloud_run_service.py`

### Security And Config

- [Token Verification](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/security/auth.py): `app/security/auth.py`
- [Application Settings](https://github.com/gsarankumar29/gcp-sre-voice-dispatcher/blob/main/app/config.py): `app/config.py`

### Other components

- **Cloud Run Failure**
- **Google Cloud Alert**
- **Pub/Sub Topic**
- **Push Subscription**
- **Direct Alert Sender**
- **Vapi API**
- **On-Call Engineer**
- **Vapi Assistant**
- **Cloud Run Jobs**

## Connections

- Cloud Run Failure → Google Cloud Alert: raises alert (evidence: `README.md`)
- Google Cloud Alert → Pub/Sub Topic: publishes alert (evidence: `README.md`)
- Pub/Sub Topic → Push Subscription: delivers messages (evidence: `README.md`)
- Push Subscription → FastAPI Dispatcher: posts alerts (evidence: `README.md`)
- Direct Alert Sender → FastAPI Dispatcher: posts alert (evidence: `README.md`)
- FastAPI Dispatcher → Alert Payload Model: validates payload (evidence: `app/main.py`)
- FastAPI Dispatcher → Token Verification: requires token check (evidence: `app/main.py`)
- Token Verification → Application Settings: checks configured token (evidence: `app/security/auth.py`)
- FastAPI Dispatcher → Severity Filter: checks severity (evidence: `app/main.py`)
- FastAPI Dispatcher → Voice Dispatch Service: requests dispatch (evidence: `app/main.py`)
- Voice Dispatch Service → Application Settings: reads dispatch settings (evidence: `app/services/vapi_service.py`)
- Voice Dispatch Service → Simulation Mode: selects simulation (evidence: `app/services/vapi_service.py`)
- Voice Dispatch Service → Vapi API: requests outbound call (evidence: `app/services/vapi_service.py`)
- Vapi API → On-Call Engineer: places voice call (evidence: `README.md`)
- Vapi Assistant → Vapi Tools Endpoint: calls tool webhook (evidence: `README.md`)
- Vapi Tools Endpoint → Tool Dispatch: dispatches tool calls (evidence: `app/api/vapi_tools.py`)
- Tool Dispatch → Incident Acknowledgement: handles acknowledge (evidence: `app/api/vapi_tools.py`)
- Tool Dispatch → Cloud Run Job Service: requests job retry (evidence: `app/api/vapi_tools.py`)
- Cloud Run Job Service → Application Settings: reads job configuration (evidence: `app/services/cloud_run_service.py`)
- Cloud Run Job Service → Cloud Run Jobs: starts job execution (evidence: `app/services/cloud_run_service.py`)
