# saumysingh01/binary-hacks-p10-prototype architecture

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

- Interactive diagram: https://gitdiagram.com/saumysingh01/binary-hacks-p10-prototype
- Repository: https://github.com/saumysingh01/binary-hacks-p10-prototype

## Overview

This is an AI-assisted expense approval service whose decisions are anchored to a local hash-linked ledger. A caller submits an expense to the API; the agent loads recent decisions for context, asks Groq for a decision, and appends the result to the chain. Separate API routes expose chain contents, integrity checks, and recent decisions, while the root route serves the dashboard. The supplied tree and excerpts support the API and ledger paths; frontend request wiring is not shown.

Main entry points: [`agent/expense_agent.py`](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/agent/expense_agent.py) (Expense evaluation), [`api/routes.py`](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/api/routes.py) (REST API), [`blockchain/chain.py`](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/blockchain/chain.py) (Chain operations), [`data/chain.json`](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/data/chain.json) (Persistent chain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and startup"]
  node_main["Server startup<br/>[main.py]"]
  node_routes["REST API<br/>[routes.py]"]
  node_chain_queries["Chain and decision queries<br/>[routes.py]"]
  node_integrity["Integrity annotation<br/>[routes.py]"]
end

subgraph group_agent["Decision agent"]
  node_agent_logic["Expense evaluation<br/>[expense_agent.py]"]
end

subgraph group_ledger["Blockchain ledger"]
  node_blockchain["Chain operations<br/>[chain.py]"]
  node_chain_file[("Persistent chain<br/>[chain.json]")]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_file["Dashboard page<br/>[index.html]"]
end

node_caller(("Expense submitter"))
node_groq{{"Groq LLM"}}

node_main -->|"starts server"| node_routes
node_caller -->|"submits expense"| node_routes
node_routes -->|"evaluates request"| node_agent_logic
node_agent_logic -->|"loads history"| node_blockchain
node_blockchain -->|"reads chain"| node_chain_file
node_blockchain -->|"returns history"| node_agent_logic
node_agent_logic -->|"requests decision"| node_groq
node_groq -->|"returns response"| node_agent_logic
node_agent_logic -->|"appends decision"| node_blockchain
node_blockchain -->|"persists blocks"| node_chain_file
node_routes -->|"handles queries"| node_chain_queries
node_chain_queries -->|"reads blocks"| node_chain_file
node_chain_queries -->|"checks integrity"| node_integrity
node_routes -->|"serves page"| node_dashboard_file

click node_main "https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/main.py"
click node_routes "https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/api/routes.py"
click node_agent_logic "https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/agent/expense_agent.py"
click node_blockchain "https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/blockchain/chain.py"
click node_chain_file "https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/data/chain.json"
click node_chain_queries "https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/api/routes.py"
click node_integrity "https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/api/routes.py"
click node_dashboard_file "https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/frontend/index.html"

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_main,node_routes,node_chain_queries,node_integrity toneBlue
class node_agent_logic toneAmber
class node_blockchain,node_chain_file toneMint
class node_dashboard_file toneRose
class node_caller,node_groq toneIndigo
```

## Components

### API and startup

- [Server startup](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/main.py): `main.py`
- [REST API](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/api/routes.py): `api/routes.py`
- [Chain and decision queries](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/api/routes.py): `api/routes.py`
- [Integrity annotation](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/api/routes.py): `api/routes.py`

### Decision agent

- [Expense evaluation](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/agent/expense_agent.py): `agent/expense_agent.py`

### Blockchain ledger

- [Chain operations](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/blockchain/chain.py): `blockchain/chain.py`
- [Persistent chain](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/data/chain.json): `data/chain.json`

### Dashboard

- [Dashboard page](https://github.com/saumysingh01/binary-hacks-p10-prototype/blob/main/frontend/index.html): `frontend/index.html`

### Other components

- **Expense submitter**
- **Groq LLM**

## Connections

- Server startup → REST API: starts server
- Expense submitter → REST API: submits expense
- REST API → Expense evaluation: evaluates request
- Expense evaluation → Chain operations: loads history
- Chain operations → Persistent chain: reads chain
- Chain operations → Expense evaluation: returns history
- Expense evaluation → Groq LLM: requests decision
- Groq LLM → Expense evaluation: returns response
- Expense evaluation → Chain operations: appends decision
- Chain operations → Persistent chain: persists blocks
- REST API → Chain and decision queries: handles queries
- Chain and decision queries → Persistent chain: reads blocks
- Chain and decision queries → Integrity annotation: checks integrity
- REST API → Dashboard page: serves page