# pradhan-not-found/checkpost architecture

> Architecture diagram of the GitHub repository pradhan-not-found/checkpost, 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/pradhan-not-found/checkpost
- Repository: https://github.com/pradhan-not-found/checkpost

## Overview

Checkpost is an AI-agent security and monitoring dashboard. Its principal documented flow sends an agent request through the proxy, evaluates policy and usage controls, then forwards permitted requests to an LLM provider and returns the response; the proxy also records usage and traces. Operators manage agents, policies, monitoring, settings, and held actions through the dashboard. The proxy and Firestore helpers are evidenced in source excerpts; several dashboard and HITL relationships are documented in the README, while their runtime implementation was not sampled.

Main entry points: [`src/lib/db.ts`](https://github.com/pradhan-not-found/checkpost/blob/main/src/lib/db.ts) (Firestore state), [`src/app/api/proxy/route.ts`](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/proxy/route.ts) (Request proxy), [`src/context/DatabaseContext.tsx`](https://github.com/pradhan-not-found/checkpost/blob/main/src/context/DatabaseContext.tsx) (Live database context), [`src/app/dashboard`](https://github.com/pradhan-not-found/checkpost/tree/main/src/app/dashboard) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Operator dashboard"]
  node_dashboard["Dashboard"]
  node_agentmgmt["Agent management<br/>[page.tsx]"]
  node_overview["System overview<br/>[page.tsx]"]
  node_audit["Audit logs<br/>[page.tsx]"]
  node_policyui["Policy management<br/>[page.tsx]"]
  node_settings["Provider settings<br/>[page.tsx]"]
  node_llmtest["LLM testing<br/>[page.tsx]"]
  node_threats["Threat monitoring<br/>[page.tsx]"]
end

subgraph group_gateway["Agent control plane"]
  node_proxy["Request proxy<br/>[route.ts]"]
  node_firewall["Policy and spend checks<br/>[route.ts]"]
  node_hitl["Human review queue<br/>[page.tsx]"]
  node_agentsapi["Agent registration API<br/>[route.ts]"]
  node_policyapi["Agent policy API<br/>[route.ts]"]
  node_ingest["Trace ingestion API<br/>[route.ts]"]
  node_dbapi["Dashboard data API<br/>[route.ts]"]
end

subgraph group_data["State and identity"]
  node_database[("Firestore state<br/>[db.ts]")]
  node_livecontext["Live database context"]
  node_auth["Authentication<br/>[AuthContext.tsx]"]
  node_firebase["Firebase clients<br/>[firebase.ts]"]
end

node_operator(("Admin operator"))
node_agent{{"AI agent"}}
node_providers{{"External LLM providers"}}

node_operator -->|"uses"| node_dashboard
node_agent -->|"submits request"| node_proxy
node_proxy -->|"evaluates request"| node_firewall
node_firewall -->|"loads rules"| node_database
node_firewall -.->|"holds sensitive action"| node_hitl
node_operator -.->|"approves or rejects"| node_hitl
node_firewall -->|"forwards allowed request"| node_providers
node_proxy -->|"calls provider"| node_providers
node_providers -->|"returns output"| node_proxy
node_proxy -->|"returns response"| node_agent
node_proxy -->|"reads and records usage"| node_database
node_agentsapi -->|"saves agents"| node_database
node_policyapi -->|"uses database"| node_database
node_ingest -->|"uses database"| node_database
node_dbapi -->|"reads and updates"| node_database
node_database -->|"persists through"| node_firebase
node_livecontext -->|"subscribes to Firestore"| node_firebase
node_dashboard -->|"syncs state"| node_livecontext
node_dashboard -->|"uses authentication"| node_auth
node_agentmgmt -->|"reads state"| node_livecontext
node_overview -->|"reads state"| node_livecontext
node_audit -->|"reads state"| node_livecontext
node_policyui -->|"reads state"| node_livecontext
node_settings -->|"uses authentication"| node_auth
node_operator -->|"manages agents"| node_agentmgmt
node_operator -->|"configures policies"| node_policyui
node_operator -->|"reviews traces"| node_audit

click node_dashboard "https://github.com/pradhan-not-found/checkpost/tree/main/src/app/dashboard"
click node_agentmgmt "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/agents/page.tsx"
click node_overview "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/page.tsx"
click node_audit "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/logs/page.tsx"
click node_policyui "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/policies/page.tsx"
click node_settings "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/settings/page.tsx"
click node_llmtest "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/llm-test/page.tsx"
click node_threats "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/threats/page.tsx"
click node_proxy "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/proxy/route.ts"
click node_firewall "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/proxy/route.ts"
click node_hitl "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/chapter/hitl/page.tsx"
click node_agentsapi "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/agents/route.ts"
click node_policyapi "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/agent/policies/route.ts"
click node_ingest "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/agent/ingest/route.ts"
click node_dbapi "https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/db/route.ts"
click node_database "https://github.com/pradhan-not-found/checkpost/blob/main/src/lib/db.ts"
click node_livecontext "https://github.com/pradhan-not-found/checkpost/blob/main/src/context/DatabaseContext.tsx"
click node_auth "https://github.com/pradhan-not-found/checkpost/blob/main/src/context/AuthContext.tsx"
click node_firebase "https://github.com/pradhan-not-found/checkpost/blob/main/src/lib/firebase.ts"

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_dashboard,node_agentmgmt,node_overview,node_audit,node_policyui,node_settings,node_llmtest,node_threats toneBlue
class node_proxy,node_firewall,node_hitl,node_agentsapi,node_policyapi,node_ingest,node_dbapi toneAmber
class node_database,node_livecontext,node_auth,node_firebase toneMint
class node_operator,node_agent,node_providers toneIndigo
```

## Components

### Operator dashboard

- [Dashboard](https://github.com/pradhan-not-found/checkpost/tree/main/src/app/dashboard): `src/app/dashboard`
- [Agent management](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/agents/page.tsx): `src/app/dashboard/agents/page.tsx`
- [System overview](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Audit logs](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/logs/page.tsx): `src/app/dashboard/logs/page.tsx`
- [Policy management](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/policies/page.tsx): `src/app/dashboard/policies/page.tsx`
- [Provider settings](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/settings/page.tsx): `src/app/dashboard/settings/page.tsx`
- [LLM testing](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/llm-test/page.tsx): `src/app/dashboard/llm-test/page.tsx`
- [Threat monitoring](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/dashboard/threats/page.tsx): `src/app/dashboard/threats/page.tsx`

### Agent control plane

- [Request proxy](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/proxy/route.ts): `src/app/api/proxy/route.ts`
- [Policy and spend checks](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/proxy/route.ts): `src/app/api/proxy/route.ts`
- [Human review queue](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/chapter/hitl/page.tsx): `src/app/chapter/hitl/page.tsx`
- [Agent registration API](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/agents/route.ts): `src/app/api/agents/route.ts`
- [Agent policy API](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/agent/policies/route.ts): `src/app/api/agent/policies/route.ts`
- [Trace ingestion API](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/agent/ingest/route.ts): `src/app/api/agent/ingest/route.ts`
- [Dashboard data API](https://github.com/pradhan-not-found/checkpost/blob/main/src/app/api/db/route.ts): `src/app/api/db/route.ts`

### State and identity

- [Firestore state](https://github.com/pradhan-not-found/checkpost/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Live database context](https://github.com/pradhan-not-found/checkpost/blob/main/src/context/DatabaseContext.tsx): `src/context/DatabaseContext.tsx`
- [Authentication](https://github.com/pradhan-not-found/checkpost/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Firebase clients](https://github.com/pradhan-not-found/checkpost/blob/main/src/lib/firebase.ts): `src/lib/firebase.ts`

### Other components

- **Admin operator**
- **AI agent**
- **External LLM providers**

## Connections

- Admin operator → Dashboard: uses (evidence: `README.md`)
- AI agent → Request proxy: submits request (evidence: `README.md`)
- Request proxy → Policy and spend checks: evaluates request (evidence: `README.md`)
- Policy and spend checks → Firestore state: loads rules (evidence: `README.md`)
- Policy and spend checks → Human review queue: holds sensitive action (evidence: `README.md`)
- Admin operator → Human review queue: approves or rejects (evidence: `README.md`)
- Policy and spend checks → External LLM providers: forwards allowed request (evidence: `README.md`)
- Request proxy → External LLM providers: calls provider (evidence: `src/app/api/proxy/route.ts`)
- External LLM providers → Request proxy: returns output (evidence: `README.md`)
- Request proxy → AI agent: returns response (evidence: `README.md`)
- Request proxy → Firestore state: reads and records usage (evidence: `src/app/api/proxy/route.ts`)
- Agent registration API → Firestore state: saves agents (evidence: `src/app/api/agents/route.ts`)
- Agent policy API → Firestore state: uses database (evidence: `src/app/api/agent/policies/route.ts`)
- Trace ingestion API → Firestore state: uses database (evidence: `src/app/api/agent/ingest/route.ts`)
- Dashboard data API → Firestore state: reads and updates (evidence: `src/app/api/db/route.ts`)
- Firestore state → Firebase clients: persists through (evidence: `src/lib/db.ts`)
- Live database context → Firebase clients: subscribes to Firestore (evidence: `src/context/DatabaseContext.tsx`)
- Dashboard → Live database context: syncs state (evidence: `README.md`)
- Dashboard → Authentication: uses authentication (evidence: `README.md`)
- Agent management → Live database context: reads state (evidence: `src/app/dashboard/agents/page.tsx`)
- System overview → Live database context: reads state (evidence: `src/app/dashboard/page.tsx`)
- Audit logs → Live database context: reads state (evidence: `src/app/dashboard/logs/page.tsx`)
- Policy management → Live database context: reads state (evidence: `src/app/dashboard/policies/page.tsx`)
- Provider settings → Authentication: uses authentication (evidence: `src/app/dashboard/settings/page.tsx`)
- Admin operator → Agent management: manages agents (evidence: `README.md`)
- Admin operator → Policy management: configures policies (evidence: `README.md`)
- Admin operator → Audit logs: reviews traces (evidence: `README.md`)
