# dashcoder/agent-api architecture

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

- Interactive diagram: https://gitdiagram.com/dashcoder/agent-api
- Repository: https://github.com/dashcoder/agent-api

## Overview

agent-api is a FastAPI backend that serves a chat/admin UI while keeping Hermes credentials server-side. Its main visitor workflow creates and owns a session, accepts a message and optional attachments, streams agent events back as SSE, and persists conversation state. Separate branches cover visitor identity and saved work, administration, plugin-provided tools, model controls, and optional voice/avatar and OpenRouter observability. Unsampled router behavior is included only where the README documents the capability; several links are therefore documented rather than source-verified.

Main entry points: [`app/routers/chat.py`](https://github.com/dashcoder/agent-api/blob/main/app/routers/chat.py) (Chat API), [`app/db.py`](https://github.com/dashcoder/agent-api/blob/main/app/db.py) (SQLite store), [`app/hermes.py`](https://github.com/dashcoder/agent-api/blob/main/app/hermes.py) (Agent adapter), [`app/plugins.py`](https://github.com/dashcoder/agent-api/blob/main/app/plugins.py) (Plugin runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Chat and agents"]
  node_chat["Chat API<br/>[chat.py]"]
  node_agent["Agent adapter<br/>[hermes.py]"]
  node_app["App assembly<br/>[main.py]"]
end

subgraph group_identity["Visitors and admin"]
  node_db[("SQLite store<br/>[db.py]")]
  node_auth["Visitor auth<br/>[auth.py]"]
  node_user["Saved work<br/>[user.py]"]
  node_files["File uploads<br/>[files.py]"]
  node_admin["Admin API<br/>[admin.py]"]
  node_console["Admin console<br/>[console.py]"]
end

subgraph group_extensions["Plugins and models"]
  node_plugin_runtime["Plugin runtime<br/>[plugins.py]"]
  node_plugin_admin["Plugin management<br/>[plugins_admin.py]"]
  node_mcp["MCP endpoint<br/>[mcp.py]"]
  node_plugin_tools["Plugin tools"]
  node_models["Model controls<br/>[models.py]"]
  node_llm["LLM utilities<br/>[llm.py]"]
end

subgraph group_operations["Voice and observability"]
  node_simli["Live avatar<br/>[simli.py]"]
  node_tts["Text to speech<br/>[tts.py]"]
  node_traces["OpenRouter traces"]
end

node_ui(("Agent UI"))
node_hermes["Hermes API"]
node_simli_service["Simli API"]
node_relay["Trace relay"]

node_ui -->|"sends chat"| node_chat
node_chat -->|"stores messages"| node_db
node_chat -->|"streams requests"| node_agent
node_agent -->|"calls Responses API"| node_hermes
node_agent -->|"yields events"| node_chat
node_chat -->|"returns SSE"| node_ui
node_ui -->|"saves work"| node_user
node_user -->|"persists visitor data"| node_db
node_ui -->|"uploads attachments"| node_files
node_files -.->|"records uploads"| node_db
node_ui -->|"administers site"| node_admin
node_admin -.->|"stores settings"| node_db
node_ui -->|"views activity"| node_console
node_console -->|"reads audit and chats"| node_db
node_app -->|"installs plugins"| node_plugin_runtime
node_plugin_runtime -->|"registers tools"| node_plugin_tools
node_plugin_runtime -.->|"mounts plugin routes"| node_mcp
node_ui -->|"manages plugins"| node_plugin_admin
node_ui -.->|"manages models"| node_models
node_models -->|"uses utilities"| node_llm
node_ui -->|"requests avatar"| node_simli
node_simli -->|"requests token"| node_simli_service
node_ui -->|"requests speech"| node_tts
node_relay -->|"delivers traces"| node_traces
node_traces -->|"audits spans"| node_db
node_app -->|"mounts router"| node_chat

click node_chat "https://github.com/dashcoder/agent-api/blob/main/app/routers/chat.py"
click node_agent "https://github.com/dashcoder/agent-api/blob/main/app/hermes.py"
click node_db "https://github.com/dashcoder/agent-api/blob/main/app/db.py"
click node_auth "https://github.com/dashcoder/agent-api/blob/main/app/auth.py"
click node_user "https://github.com/dashcoder/agent-api/blob/main/app/routers/user.py"
click node_files "https://github.com/dashcoder/agent-api/blob/main/app/routers/files.py"
click node_admin "https://github.com/dashcoder/agent-api/blob/main/app/routers/admin.py"
click node_console "https://github.com/dashcoder/agent-api/blob/main/app/routers/console.py"
click node_plugin_runtime "https://github.com/dashcoder/agent-api/blob/main/app/plugins.py"
click node_plugin_admin "https://github.com/dashcoder/agent-api/blob/main/app/routers/plugins_admin.py"
click node_mcp "https://github.com/dashcoder/agent-api/blob/main/app/routers/mcp.py"
click node_models "https://github.com/dashcoder/agent-api/blob/main/app/routers/models.py"
click node_llm "https://github.com/dashcoder/agent-api/blob/main/app/llm.py"
click node_simli "https://github.com/dashcoder/agent-api/blob/main/app/routers/simli.py"
click node_tts "https://github.com/dashcoder/agent-api/blob/main/app/routers/tts.py"
click node_traces "https://github.com/dashcoder/agent-api/blob/main/app/openrouter_traces.py"
click node_app "https://github.com/dashcoder/agent-api/blob/main/app/main.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_chat,node_agent,node_app,node_ui toneBlue
class node_db,node_auth,node_user,node_files,node_admin,node_console toneAmber
class node_plugin_runtime,node_plugin_admin,node_mcp,node_plugin_tools,node_models,node_llm,node_hermes,node_simli_service toneMint
class node_simli,node_tts,node_traces toneRose
class node_relay toneIndigo
```

## Components

### Chat and agents

- [Chat API](https://github.com/dashcoder/agent-api/blob/main/app/routers/chat.py): `app/routers/chat.py`
- [Agent adapter](https://github.com/dashcoder/agent-api/blob/main/app/hermes.py): `app/hermes.py`
- [App assembly](https://github.com/dashcoder/agent-api/blob/main/app/main.py): `app/main.py`

### Visitors and admin

- [SQLite store](https://github.com/dashcoder/agent-api/blob/main/app/db.py): `app/db.py`
- [Visitor auth](https://github.com/dashcoder/agent-api/blob/main/app/auth.py): `app/auth.py`
- [Saved work](https://github.com/dashcoder/agent-api/blob/main/app/routers/user.py): `app/routers/user.py`
- [File uploads](https://github.com/dashcoder/agent-api/blob/main/app/routers/files.py): `app/routers/files.py`
- [Admin API](https://github.com/dashcoder/agent-api/blob/main/app/routers/admin.py): `app/routers/admin.py`
- [Admin console](https://github.com/dashcoder/agent-api/blob/main/app/routers/console.py): `app/routers/console.py`

### Plugins and models

- [Plugin runtime](https://github.com/dashcoder/agent-api/blob/main/app/plugins.py): `app/plugins.py`
- [Plugin management](https://github.com/dashcoder/agent-api/blob/main/app/routers/plugins_admin.py): `app/routers/plugins_admin.py`
- [MCP endpoint](https://github.com/dashcoder/agent-api/blob/main/app/routers/mcp.py): `app/routers/mcp.py`
- **Plugin tools**
- [Model controls](https://github.com/dashcoder/agent-api/blob/main/app/routers/models.py): `app/routers/models.py`
- [LLM utilities](https://github.com/dashcoder/agent-api/blob/main/app/llm.py): `app/llm.py`

### Voice and observability

- [Live avatar](https://github.com/dashcoder/agent-api/blob/main/app/routers/simli.py): `app/routers/simli.py`
- [Text to speech](https://github.com/dashcoder/agent-api/blob/main/app/routers/tts.py): `app/routers/tts.py`
- [OpenRouter traces](https://github.com/dashcoder/agent-api/blob/main/app/openrouter_traces.py): `app/openrouter_traces.py`

### Other components

- **Agent UI**
- **Hermes API**
- **Simli API**
- **Trace relay**

## Connections

- Agent UI → Chat API: sends chat (evidence: `README.md`)
- Chat API → SQLite store: stores messages (evidence: `app/routers/chat.py`)
- Chat API → Agent adapter: streams requests (evidence: `README.md`)
- Agent adapter → Hermes API: calls Responses API (evidence: `README.md`)
- Agent adapter → Chat API: yields events (evidence: `app/hermes.py`)
- Chat API → Agent UI: returns SSE (evidence: `README.md`)
- Agent UI → Saved work: saves work (evidence: `README.md`)
- Saved work → SQLite store: persists visitor data (evidence: `app/routers/user.py`)
- Agent UI → File uploads: uploads attachments (evidence: `README.md`)
- File uploads → SQLite store: records uploads
- Agent UI → Admin API: administers site (evidence: `README.md`)
- Admin API → SQLite store: stores settings (evidence: `app/routers/admin.py`)
- Agent UI → Admin console: views activity (evidence: `README.md`)
- Admin console → SQLite store: reads audit and chats (evidence: `app/routers/console.py`)
- App assembly → Plugin runtime: installs plugins (evidence: `app/main.py`)
- Plugin runtime → Plugin tools: registers tools (evidence: `app/plugins.py`)
- Plugin runtime → MCP endpoint: mounts plugin routes (evidence: `app/routers/mcp.py`)
- Agent UI → Plugin management: manages plugins (evidence: `README.md`)
- Agent UI → Model controls: manages models
- Model controls → LLM utilities: uses utilities (evidence: `app/routers/models.py`)
- Agent UI → Live avatar: requests avatar (evidence: `README.md`)
- Live avatar → Simli API: requests token (evidence: `app/routers/simli.py`)
- Agent UI → Text to speech: requests speech (evidence: `README.md`)
- Trace relay → OpenRouter traces: delivers traces (evidence: `README.md`)
- OpenRouter traces → SQLite store: audits spans (evidence: `app/openrouter_traces.py`)
- App assembly → Chat API: mounts router (evidence: `app/main.py`)