# prashant-thakur77/beacon architecture

> Architecture diagram of the GitHub repository prashant-thakur77/beacon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prashant-thakur77/beacon
- Repository: https://github.com/prashant-thakur77/beacon

## Overview

Beacon is a voice-first AWS incident-response agent. Its core workflow is alarm intake, evidence gathering and diagnosis, transcript-checked approval, constrained remediation, and recovery verification; recurring incidents may instead use a scoped Sleep Contract. The README documents the major AWS integrations and UI capabilities, while sampled source confirms portions of the incident handler, voice flow, browser speech path, and security-group actions. Some subsystem wiring is therefore shown only where documented.

Main entry points: [`src/beacon/handler.py`](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/handler.py) (Incident handler), [`src/beacon/remediate.py`](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/remediate.py) (Remediation workflow), [`src/beacon/voice_tools.py`](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/voice_tools.py) (Agent tools), [`src/beacon/store.py`](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/store.py) (Incident and approval store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_incident["Incident analysis"]
  node_handler["Incident handler<br/>[handler.py]"]
  node_triage["Log triage<br/>[triage.py]"]
  node_analyzer["Log analysis<br/>[analyzer.py]"]
  node_changes["Change ledger<br/>[changes.py]"]
  node_diagnose["Deterministic diagnosis<br/>[diagnose.py]"]
end

subgraph group_conversation["Voice and consent"]
  node_talk["Incident conversation<br/>[Talk.tsx]"]
  node_transcribe["Streaming speech input<br/>[transcribe.ts]"]
  node_voice["Voice turn handler<br/>[voice_turn.py]"]
  node_tools["Agent tools<br/>[voice_tools.py]"]
  node_context["Turn consent context<br/>[turn_context.py]"]
  node_contracts["Sleep contracts<br/>[contracts.py]"]
end

subgraph group_remediation["Safe remediation"]
  node_step["Remediation workflow<br/>[remediate.py]"]
  node_registry["Action allowlist<br/>[registry.py]"]
  node_sg["Security-group actions<br/>[actions_sg.py]"]
  node_verify["Recovery verification<br/>[verify.py]"]
end

subgraph group_state["Incident state"]
  node_store["Incident and approval store<br/>[store.py]"]
end

subgraph group_console["Night Board console"]
  node_app["Console application<br/>[App.tsx]"]
  node_dashboard["Dashboard API<br/>[dashboard_api.py]"]
  node_reports["Analytics and reports<br/>[Reports.tsx]"]
end

node_alarm(("CloudWatch alarm"))
node_bedrock{{"Amazon Bedrock"}}
node_cloudtrail{{"CloudTrail events"}}
node_engineer(("On-call engineer"))
node_browser(("Browser console"))
node_dynamo[("DynamoDB")]
node_cloudwatch{{"CloudWatch metrics"}}
node_awsresources{{"AWS patient resources"}}
node_sns{{"SNS notifications"}}

node_alarm -->|"triggers"| node_handler
node_handler -->|"requests analysis"| node_triage
node_triage -->|"analyzes logs"| node_bedrock
node_handler -->|"reduces logs"| node_analyzer
node_handler -->|"checks changes"| node_changes
node_changes -->|"reads events"| node_cloudtrail
node_handler -->|"runs diagnostics"| node_diagnose
node_diagnose -->|"checks drift"| node_awsresources
node_handler -->|"records incident"| node_store
node_store -->|"reads and writes"| node_dynamo
node_handler -->|"pages or reports"| node_sns
node_browser -->|"opens console"| node_app
node_app -->|"shows conversation"| node_talk
node_engineer -->|"speaks or types"| node_talk
node_talk -->|"streams audio"| node_transcribe
node_transcribe -->|"returns transcript"| node_engineer
node_talk -->|"submits turn"| node_voice
node_voice -->|"dispatches tools"| node_tools
node_voice -->|"reasons with"| node_bedrock
node_voice -->|"sets transcript"| node_context
node_tools -->|"checks consent"| node_context
node_tools -->|"reads incident"| node_store
node_tools -->|"grants or checks"| node_contracts
node_tools -->|"starts remediation"| node_step
node_handler -->|"starts contract run"| node_step
node_step -->|"selects allowed action"| node_registry
node_step -->|"executes action"| node_sg
node_sg -->|"dry-runs or changes"| node_awsresources
node_step -->|"checks recovery"| node_verify
node_verify -->|"checks alarm and metrics"| node_cloudwatch
node_verify -->|"checks rule state"| node_awsresources
node_step -->|"records outcome"| node_store
node_step -->|"notifies outcome"| node_sns
node_app -->|"loads console data"| node_dashboard
node_dashboard -->|"reads incidents"| node_store
node_app -->|"shows audit and reports"| node_reports

click node_handler "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/handler.py"
click node_triage "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/triage.py"
click node_analyzer "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/analyzer.py"
click node_changes "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/changes.py"
click node_diagnose "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/diagnose.py"
click node_app "https://github.com/prashant-thakur77/beacon/blob/main/web/src/App.tsx"
click node_talk "https://github.com/prashant-thakur77/beacon/blob/main/web/src/components/Talk.tsx"
click node_transcribe "https://github.com/prashant-thakur77/beacon/blob/main/web/src/voice/transcribe.ts"
click node_voice "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/voice_turn.py"
click node_tools "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/voice_tools.py"
click node_context "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/turn_context.py"
click node_contracts "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/contracts.py"
click node_step "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/remediate.py"
click node_registry "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/remediation/registry.py"
click node_sg "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/remediation/actions_sg.py"
click node_verify "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/remediation/verify.py"
click node_store "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/store.py"
click node_dashboard "https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/dashboard_api.py"
click node_reports "https://github.com/prashant-thakur77/beacon/blob/main/web/src/components/Reports.tsx"

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_handler,node_triage,node_analyzer,node_changes,node_diagnose,node_browser toneBlue
class node_talk,node_transcribe,node_voice,node_tools,node_context,node_contracts,node_dynamo toneAmber
class node_step,node_registry,node_sg,node_verify toneMint
class node_store toneRose
class node_app,node_dashboard,node_reports,node_alarm,node_bedrock,node_cloudtrail,node_engineer,node_cloudwatch,node_awsresources,node_sns toneIndigo
```

## Components

### Incident analysis

- [Incident handler](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/handler.py): `src/beacon/handler.py`
- [Log triage](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/triage.py): `src/beacon/triage.py`
- [Log analysis](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/analyzer.py): `src/beacon/analyzer.py`
- [Change ledger](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/changes.py): `src/beacon/changes.py`
- [Deterministic diagnosis](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/diagnose.py): `src/beacon/diagnose.py`

### Voice and consent

- [Incident conversation](https://github.com/prashant-thakur77/beacon/blob/main/web/src/components/Talk.tsx): `web/src/components/Talk.tsx`
- [Streaming speech input](https://github.com/prashant-thakur77/beacon/blob/main/web/src/voice/transcribe.ts): `web/src/voice/transcribe.ts`
- [Voice turn handler](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/voice_turn.py): `src/beacon/voice_turn.py`
- [Agent tools](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/voice_tools.py): `src/beacon/voice_tools.py`
- [Turn consent context](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/turn_context.py): `src/beacon/turn_context.py`
- [Sleep contracts](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/contracts.py): `src/beacon/contracts.py`

### Safe remediation

- [Remediation workflow](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/remediate.py): `src/beacon/remediate.py`
- [Action allowlist](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/remediation/registry.py): `src/beacon/remediation/registry.py`
- [Security-group actions](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/remediation/actions_sg.py): `src/beacon/remediation/actions_sg.py`
- [Recovery verification](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/remediation/verify.py): `src/beacon/remediation/verify.py`

### Incident state

- [Incident and approval store](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/store.py): `src/beacon/store.py`

### Night Board console

- [Console application](https://github.com/prashant-thakur77/beacon/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Dashboard API](https://github.com/prashant-thakur77/beacon/blob/main/src/beacon/dashboard_api.py): `src/beacon/dashboard_api.py`
- [Analytics and reports](https://github.com/prashant-thakur77/beacon/blob/main/web/src/components/Reports.tsx): `web/src/components/Reports.tsx`

### Other components

- **CloudWatch alarm**
- **Amazon Bedrock**
- **CloudTrail events**
- **On-call engineer**
- **Browser console**
- **DynamoDB**
- **CloudWatch metrics**
- **AWS patient resources**
- **SNS notifications**

## Connections

- CloudWatch alarm → Incident handler: triggers
- Incident handler → Log triage: requests analysis
- Log triage → Amazon Bedrock: analyzes logs
- Incident handler → Log analysis: reduces logs
- Incident handler → Change ledger: checks changes
- Change ledger → CloudTrail events: reads events
- Incident handler → Deterministic diagnosis: runs diagnostics
- Deterministic diagnosis → AWS patient resources: checks drift
- Incident handler → Incident and approval store: records incident
- Incident and approval store → DynamoDB: reads and writes
- Incident handler → SNS notifications: pages or reports
- Browser console → Console application: opens console
- Console application → Incident conversation: shows conversation
- On-call engineer → Incident conversation: speaks or types
- Incident conversation → Streaming speech input: streams audio
- Streaming speech input → On-call engineer: returns transcript
- Incident conversation → Voice turn handler: submits turn
- Voice turn handler → Agent tools: dispatches tools
- Voice turn handler → Amazon Bedrock: reasons with
- Voice turn handler → Turn consent context: sets transcript
- Agent tools → Turn consent context: checks consent
- Agent tools → Incident and approval store: reads incident
- Agent tools → Sleep contracts: grants or checks
- Agent tools → Remediation workflow: starts remediation
- Incident handler → Remediation workflow: starts contract run
- Remediation workflow → Action allowlist: selects allowed action
- Remediation workflow → Security-group actions: executes action
- Security-group actions → AWS patient resources: dry-runs or changes
- Remediation workflow → Recovery verification: checks recovery
- Recovery verification → CloudWatch metrics: checks alarm and metrics
- Recovery verification → AWS patient resources: checks rule state
- Remediation workflow → Incident and approval store: records outcome
- Remediation workflow → SNS notifications: notifies outcome
- Console application → Dashboard API: loads console data
- Dashboard API → Incident and approval store: reads incidents
- Console application → Analytics and reports: shows audit and reports