# alihon20807-debug/forgeai-hackathon architecture

> Architecture diagram of the GitHub repository alihon20807-debug/forgeai-hackathon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alihon20807-debug/forgeai-hackathon
- Repository: https://github.com/alihon20807-debug/forgeai-hackathon

## Overview

ClaimGuard is a voice-first FNOL agent: a caller’s speech is transcribed and redacted, the agent proposes claim and dispatch actions, deterministic safeguards govern consequential actions and responses, and verified state and traces support live supervision. The README documents the supervisor console and PRISM diagnostics; sampled source confirms key service, redaction, tool, enforcement, retrieval, storage, and tracing relationships. Some UI wiring and unsampled subsystem details are documented but not verified in source excerpts.

Main entry points: [`app/server.py`](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/server.py) (FastAPI Service), [`app/agent/runner.py`](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/agent/runner.py) (Agent Runner), [`app/db/database.py`](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/db/database.py) (SQLite Records), [`app/agent/tools.py`](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/agent/tools.py) (Agent Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Caller &amp; Console"]
  node_console["Live Console<br/>[app.js]"]
  node_phone_ui["Phone UI<br/>[phone.js]"]
end

subgraph group_conversation["Conversation Processing"]
  node_api["FastAPI Service<br/>[server.py]"]
  node_dev_server["Development Server<br/>[dev_server.py]"]
  node_transcriber["Voice Transcriber<br/>[transcriber.py]"]
  node_runner["Agent Runner<br/>[runner.py]"]
  node_prompts["Agent Prompts<br/>[prompts.py]"]
  node_tools["Agent Tools<br/>[tools.py]"]
  node_config["Runtime Config<br/>[config.py]"]
end

subgraph group_guardrails["Deterministic Safeguards"]
  node_pii["PII Shield<br/>[pii_shield.py]"]
  node_commit["Commit Window<br/>[commit_window.py]"]
  node_veto["Outbound Veto<br/>[outbound_veto.py]"]
  node_policy_latch["Policy Latch<br/>[schema.sql]"]
end

subgraph group_records["Records &amp; Policy"]
  node_database[("SQLite Records<br/>[database.py]")]
  node_retriever["Policy Retriever<br/>[retriever.py]"]
  node_corpus["Policy Corpus<br/>[corpus.py]"]
end

subgraph group_telemetry["Observability"]
  node_tracer["PRISM Tracer<br/>[prism_tracer.py]"]
end

node_caller(("Caller"))
node_supervisor(("Supervisor"))
node_llm["LLM Service"]
node_prism["PRISM Service"]

node_caller -->|"speaks to"| node_phone_ui
node_phone_ui -.->|"sends turns"| node_api
node_api -.->|"routes audio"| node_transcriber
node_transcriber -->|"redacts with"| node_pii
node_api -->|"redacts with"| node_pii
node_api -.->|"processes turns"| node_runner
node_runner -->|"uses prompts"| node_prompts
node_runner -.->|"requests generation"| node_llm
node_runner -->|"dispatches tools"| node_tools
node_tools -->|"reads and writes"| node_database
node_tools -->|"stages actions"| node_commit
node_tools -->|"searches policies"| node_retriever
node_retriever -->|"searches chunks"| node_corpus
node_runner -->|"uses window"| node_commit
node_runner -->|"filters response"| node_veto
node_commit -->|"persists transitions"| node_database
node_database -.->|"enforces triggers"| node_policy_latch
node_api -->|"looks up policy"| node_database
node_api -->|"clears session"| node_commit
node_api -->|"traces turns"| node_tracer
node_tracer -->|"ingests spans"| node_prism
node_api -.->|"broadcasts updates"| node_console
node_supervisor -->|"monitors calls"| node_console
node_dev_server -->|"uses transcription"| node_transcriber
node_dev_server -->|"uses redaction"| node_pii
node_runner -->|"uses settings"| node_config
node_database -->|"reads database path"| node_config
node_tracer -->|"reads telemetry settings"| node_config

click node_console "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/frontend/app.js"
click node_phone_ui "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/frontend/phone.js"
click node_api "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/server.py"
click node_dev_server "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/dev_server.py"
click node_transcriber "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/voice/transcriber.py"
click node_pii "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/security/pii_shield.py"
click node_runner "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/agent/runner.py"
click node_prompts "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/agent/prompts.py"
click node_tools "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/agent/tools.py"
click node_commit "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/enforcement/commit_window.py"
click node_veto "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/enforcement/outbound_veto.py"
click node_policy_latch "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/db/schema.sql"
click node_database "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/db/database.py"
click node_retriever "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/rag/retriever.py"
click node_corpus "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/rag/corpus.py"
click node_config "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/config.py"
click node_tracer "https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/observability/prism_tracer.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_console,node_phone_ui toneBlue
class node_api,node_dev_server,node_transcriber,node_runner,node_prompts,node_tools,node_config toneAmber
class node_pii,node_commit,node_veto,node_policy_latch toneMint
class node_database,node_retriever,node_corpus toneRose
class node_tracer,node_caller,node_supervisor,node_llm,node_prism toneIndigo
```

## Components

### Caller & Console

- [Live Console](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/frontend/app.js): `frontend/app.js`
- [Phone UI](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/frontend/phone.js): `frontend/phone.js`

### Conversation Processing

- [FastAPI Service](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/server.py): `app/server.py`
- [Development Server](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/dev_server.py): `app/dev_server.py`
- [Voice Transcriber](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/voice/transcriber.py): `app/voice/transcriber.py`
- [Agent Runner](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/agent/runner.py): `app/agent/runner.py`
- [Agent Prompts](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/agent/prompts.py): `app/agent/prompts.py`
- [Agent Tools](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/agent/tools.py): `app/agent/tools.py`
- [Runtime Config](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/config.py): `app/config.py`

### Deterministic Safeguards

- [PII Shield](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/security/pii_shield.py): `app/security/pii_shield.py`
- [Commit Window](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/enforcement/commit_window.py): `app/enforcement/commit_window.py`
- [Outbound Veto](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/enforcement/outbound_veto.py): `app/enforcement/outbound_veto.py`
- [Policy Latch](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/db/schema.sql): `app/db/schema.sql`

### Records & Policy

- [SQLite Records](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/db/database.py): `app/db/database.py`
- [Policy Retriever](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/rag/retriever.py): `app/rag/retriever.py`
- [Policy Corpus](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/rag/corpus.py): `app/rag/corpus.py`

### Observability

- [PRISM Tracer](https://github.com/alihon20807-debug/forgeai-hackathon/blob/main/app/observability/prism_tracer.py): `app/observability/prism_tracer.py`

### Other components

- **Caller**
- **Supervisor**
- **LLM Service**
- **PRISM Service**

## Connections

- Caller → Phone UI: speaks to (evidence: `README.md`)
- Phone UI → FastAPI Service: sends turns
- FastAPI Service → Voice Transcriber: routes audio (evidence: `app/server.py`)
- Voice Transcriber → PII Shield: redacts with (evidence: `app/voice/transcriber.py`)
- FastAPI Service → PII Shield: redacts with (evidence: `app/server.py`)
- FastAPI Service → Agent Runner: processes turns (evidence: `app/server.py`)
- Agent Runner → Agent Prompts: uses prompts (evidence: `app/agent/runner.py`)
- Agent Runner → LLM Service: requests generation
- Agent Runner → Agent Tools: dispatches tools (evidence: `app/agent/runner.py`)
- Agent Tools → SQLite Records: reads and writes (evidence: `app/agent/tools.py`)
- Agent Tools → Commit Window: stages actions (evidence: `app/agent/tools.py`)
- Agent Tools → Policy Retriever: searches policies (evidence: `app/agent/tools.py`)
- Policy Retriever → Policy Corpus: searches chunks (evidence: `app/rag/retriever.py`)
- Agent Runner → Commit Window: uses window (evidence: `app/agent/runner.py`)
- Agent Runner → Outbound Veto: filters response (evidence: `app/agent/runner.py`)
- Commit Window → SQLite Records: persists transitions (evidence: `app/enforcement/commit_window.py`)
- SQLite Records → Policy Latch: enforces triggers
- FastAPI Service → SQLite Records: looks up policy (evidence: `app/server.py`)
- FastAPI Service → Commit Window: clears session (evidence: `app/server.py`)
- FastAPI Service → PRISM Tracer: traces turns (evidence: `app/server.py`)
- PRISM Tracer → PRISM Service: ingests spans (evidence: `app/observability/prism_tracer.py`)
- FastAPI Service → Live Console: broadcasts updates
- Supervisor → Live Console: monitors calls (evidence: `README.md`)
- Development Server → Voice Transcriber: uses transcription (evidence: `app/dev_server.py`)
- Development Server → PII Shield: uses redaction (evidence: `app/dev_server.py`)
- Agent Runner → Runtime Config: uses settings (evidence: `app/agent/runner.py`)
- SQLite Records → Runtime Config: reads database path (evidence: `app/db/database.py`)
- PRISM Tracer → Runtime Config: reads telemetry settings (evidence: `app/observability/prism_tracer.py`)
