# harrish8248/ambient-expense-agent architecture

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

- Interactive diagram: https://gitdiagram.com/harrish8248/ambient-expense-agent
- Repository: https://github.com/harrish8248/ambient-expense-agent

## Overview

Ambient Expense Agent is an ADK-based expense-auditing application, with a separate basic assistant scaffold. The main path accepts an expense through the FastAPI/Pub/Sub service, runs threshold routing and security checks, performs Gemini risk analysis when appropriate, pauses for human decisions, then records the outcome. A separate Agent Engine runtime exposes feedback and telemetry; the basic assistant has its own weather/time tools. Workflow-stage transitions are documented in the README; service and runtime edges are limited to relationships visible in the excerpts.

Main entry points: [`expense_agent/agent_runtime_app.py`](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent_runtime_app.py) (Agent Engine runtime), [`expense_agent/agent.py`](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py) (Parse and route), [`expense_agent/service_app.py`](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/service_app.py) (FastAPI service), [`app/agent_runtime_app.py`](https://github.com/harrish8248/ambient-expense-agent/blob/main/app/agent_runtime_app.py) (Basic Agent Engine runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Service and Sessions"]
  node_service["FastAPI service<br/>[service_app.py]"]
  node_sessions[("SQLite sessions<br/>[service_app.py]")]
end

subgraph group_audit["Expense Audit Workflow"]
  node_workflow["Expense workflow<br/>[agent.py]"]
  node_parse["Parse and route<br/>[agent.py]"]
  node_threshold["Threshold settings<br/>[config.py]"]
  node_autoapprove["Auto-approve<br/>[agent.py]"]
  node_security["Security checkpoint<br/>[agent.py]"]
  node_risk["LLM risk analysis<br/>[agent.py]"]
  node_approval["Human approval<br/>[agent.py]"]
  node_outcome["Record outcome<br/>[agent.py]"]
end

subgraph group_runtime["Runtime and Observability"]
  node_agentruntime["Agent Engine runtime"]
  node_feedback["Feedback model<br/>[typing.py]"]
  node_telemetry["Telemetry setup<br/>[telemetry.py]"]
end

subgraph group_assistant["Basic Assistant"]
  node_basicagent["Basic ADK assistant<br/>[agent.py]"]
  node_basicruntime["Basic Agent Engine runtime"]
  node_basicfeedback["Feedback model<br/>[typing.py]"]
  node_basictelemetry["Telemetry setup<br/>[telemetry.py]"]
end

node_pubsub(("Pub/Sub or HTTP sender"))
node_reviewer(("Human reviewer"))
node_cloudops["Cloud Operations"]

node_pubsub -->|"sends event"| node_service
node_service -->|"reads and writes"| node_sessions
node_service -->|"runs workflow"| node_workflow
node_reviewer -->|"submits decision"| node_service
node_workflow -->|"starts at"| node_parse
node_parse -->|"uses threshold"| node_threshold
node_parse -->|"routes below threshold"| node_autoapprove
node_parse -->|"routes for review"| node_security
node_security -->|"safe: analyze"| node_risk
node_security -->|"injection: escalate"| node_approval
node_risk -->|"requests review"| node_approval
node_approval -->|"requests decision"| node_reviewer
node_approval -->|"resumes with decision"| node_outcome
node_autoapprove -->|"records approval"| node_outcome
node_agentruntime -->|"hosts app"| node_workflow
node_agentruntime -->|"sets up"| node_telemetry
node_agentruntime -->|"validates feedback"| node_feedback
node_agentruntime -->|"logs feedback"| node_cloudops
node_telemetry -->|"configures telemetry"| node_cloudops
node_basicruntime -->|"hosts app"| node_basicagent
node_basicruntime -->|"sets up"| node_basictelemetry
node_basicruntime -->|"validates feedback"| node_basicfeedback

click node_service "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/service_app.py"
click node_sessions "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/service_app.py"
click node_workflow "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py"
click node_parse "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py"
click node_threshold "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/config.py"
click node_autoapprove "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py"
click node_security "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py"
click node_risk "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py"
click node_approval "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py"
click node_outcome "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py"
click node_agentruntime "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent_runtime_app.py"
click node_feedback "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/app_utils/typing.py"
click node_telemetry "https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/app_utils/telemetry.py"
click node_basicagent "https://github.com/harrish8248/ambient-expense-agent/blob/main/app/agent.py"
click node_basicruntime "https://github.com/harrish8248/ambient-expense-agent/blob/main/app/agent_runtime_app.py"
click node_basicfeedback "https://github.com/harrish8248/ambient-expense-agent/blob/main/app/app_utils/typing.py"
click node_basictelemetry "https://github.com/harrish8248/ambient-expense-agent/blob/main/app/app_utils/telemetry.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_service,node_sessions,node_reviewer toneBlue
class node_workflow,node_parse,node_threshold,node_autoapprove,node_security,node_risk,node_approval,node_outcome toneAmber
class node_agentruntime,node_feedback,node_telemetry toneMint
class node_basicagent,node_basicruntime,node_basicfeedback,node_basictelemetry toneRose
class node_pubsub,node_cloudops toneIndigo
```

## Components

### Service and Sessions

- [FastAPI service](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/service_app.py): `expense_agent/service_app.py`
- [SQLite sessions](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/service_app.py): `expense_agent/service_app.py`

### Expense Audit Workflow

- [Expense workflow](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py): `expense_agent/agent.py`
- [Parse and route](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py): `expense_agent/agent.py`
- [Threshold settings](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/config.py): `expense_agent/config.py`
- [Auto-approve](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py): `expense_agent/agent.py`
- [Security checkpoint](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py): `expense_agent/agent.py`
- [LLM risk analysis](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py): `expense_agent/agent.py`
- [Human approval](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py): `expense_agent/agent.py`
- [Record outcome](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent.py): `expense_agent/agent.py`

### Runtime and Observability

- [Agent Engine runtime](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/agent_runtime_app.py): `expense_agent/agent_runtime_app.py`
- [Feedback model](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/app_utils/typing.py): `expense_agent/app_utils/typing.py`
- [Telemetry setup](https://github.com/harrish8248/ambient-expense-agent/blob/main/expense_agent/app_utils/telemetry.py): `expense_agent/app_utils/telemetry.py`

### Basic Assistant

- [Basic ADK assistant](https://github.com/harrish8248/ambient-expense-agent/blob/main/app/agent.py): `app/agent.py`
- [Basic Agent Engine runtime](https://github.com/harrish8248/ambient-expense-agent/blob/main/app/agent_runtime_app.py): `app/agent_runtime_app.py`
- [Feedback model](https://github.com/harrish8248/ambient-expense-agent/blob/main/app/app_utils/typing.py): `app/app_utils/typing.py`
- [Telemetry setup](https://github.com/harrish8248/ambient-expense-agent/blob/main/app/app_utils/telemetry.py): `app/app_utils/telemetry.py`

### Other components

- **Pub/Sub or HTTP sender**
- **Human reviewer**
- **Cloud Operations**

## Connections

- Pub/Sub or HTTP sender → FastAPI service: sends event (evidence: `README.md`)
- FastAPI service → SQLite sessions: reads and writes (evidence: `expense_agent/service_app.py`)
- FastAPI service → Expense workflow: runs workflow (evidence: `expense_agent/service_app.py`)
- Human reviewer → FastAPI service: submits decision (evidence: `expense_agent/service_app.py`)
- Expense workflow → Parse and route: starts at (evidence: `expense_agent/agent.py`)
- Parse and route → Threshold settings: uses threshold (evidence: `expense_agent/agent.py`)
- Parse and route → Auto-approve: routes below threshold (evidence: `README.md`)
- Parse and route → Security checkpoint: routes for review (evidence: `README.md`)
- Security checkpoint → LLM risk analysis: safe: analyze (evidence: `README.md`)
- Security checkpoint → Human approval: injection: escalate (evidence: `README.md`)
- LLM risk analysis → Human approval: requests review (evidence: `README.md`)
- Human approval → Human reviewer: requests decision (evidence: `README.md`)
- Human approval → Record outcome: resumes with decision (evidence: `README.md`)
- Auto-approve → Record outcome: records approval (evidence: `README.md`)
- Agent Engine runtime → Expense workflow: hosts app (evidence: `expense_agent/agent_runtime_app.py`)
- Agent Engine runtime → Telemetry setup: sets up (evidence: `expense_agent/agent_runtime_app.py`)
- Agent Engine runtime → Feedback model: validates feedback (evidence: `expense_agent/agent_runtime_app.py`)
- Agent Engine runtime → Cloud Operations: logs feedback (evidence: `expense_agent/agent_runtime_app.py`)
- Telemetry setup → Cloud Operations: configures telemetry (evidence: `expense_agent/app_utils/telemetry.py`)
- Basic Agent Engine runtime → Basic ADK assistant: hosts app (evidence: `app/agent_runtime_app.py`)
- Basic Agent Engine runtime → Telemetry setup: sets up (evidence: `app/agent_runtime_app.py`)
- Basic Agent Engine runtime → Feedback model: validates feedback (evidence: `app/agent_runtime_app.py`)
