# cobanov/pydantic-agent-template architecture

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

- Interactive diagram: https://gitdiagram.com/cobanov/pydantic-agent-template
- Repository: https://github.com/cobanov/pydantic-agent-template

## Overview

This is a small FastAPI template for an LLM chat agent, with a health endpoint and optional API-key authentication. The main workflow is an HTTP client sending a chat request, the chat route verifying the key and invoking the Pydantic AI agent, then returning the model output. Startup configures the app, creates database tables from the imported model metadata, and provides the agent an HTTP client dependency; the chat route does not persist conversations. Source excerpts establish these links, but do not show agent-side use of the HTTP client or database persistence.

Main entry points: [`app/routers/chat.py`](https://github.com/cobanov/pydantic-agent-template/blob/main/app/routers/chat.py) (Chat route), [`app/main.py`](https://github.com/cobanov/pydantic-agent-template/blob/main/app/main.py) (FastAPI app), [`app/agent/core.py`](https://github.com/cobanov/pydantic-agent-template/blob/main/app/agent/core.py) (Pydantic AI agent), [`app/health.py`](https://github.com/cobanov/pydantic-agent-template/blob/main/app/health.py) (Health route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_application["FastAPI app<br/>[main.py]"]
  node_chat["Chat route<br/>[chat.py]"]
  node_health["Health route<br/>[health.py]"]
  node_auth["API-key check<br/>[auth.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_version["Version config<br/>[config.py]"]
end

subgraph group_agent["Agent"]
  node_agentdeps["Agent dependencies<br/>[context.py]"]
  node_agentcore["Pydantic AI agent<br/>[core.py]"]
  node_prompt["System prompt<br/>[prompts.py]"]
end

subgraph group_state["Database"]
  node_database[("Async database<br/>[database.py]")]
  node_conversation["Conversation model<br/>[models.py]"]
end

node_client(("HTTP client"))
node_llm(("OpenAI model"))

node_client -->|"sends request"| node_chat
node_chat -->|"checks key"| node_auth
node_chat -->|"creates dependencies"| node_agentdeps
node_chat -->|"runs agent"| node_agentcore
node_chat -->|"uses request/response"| node_schemas
node_agentcore -->|"declares dependency type"| node_agentdeps
node_agentcore -->|"sets system prompt"| node_prompt
node_agentcore -->|"configures model"| node_llm
node_application -->|"registers route"| node_chat
node_application -->|"registers route"| node_health
node_application -->|"creates tables"| node_database
node_application -->|"imports metadata model"| node_conversation
node_health -->|"returns health schema"| node_schemas
node_health -->|"uses version"| node_version
node_database -->|"provides model base"| node_conversation

click node_application "https://github.com/cobanov/pydantic-agent-template/blob/main/app/main.py"
click node_chat "https://github.com/cobanov/pydantic-agent-template/blob/main/app/routers/chat.py"
click node_health "https://github.com/cobanov/pydantic-agent-template/blob/main/app/health.py"
click node_auth "https://github.com/cobanov/pydantic-agent-template/blob/main/app/auth.py"
click node_schemas "https://github.com/cobanov/pydantic-agent-template/blob/main/app/schemas.py"
click node_version "https://github.com/cobanov/pydantic-agent-template/blob/main/app/config.py"
click node_agentdeps "https://github.com/cobanov/pydantic-agent-template/blob/main/app/agent/context.py"
click node_agentcore "https://github.com/cobanov/pydantic-agent-template/blob/main/app/agent/core.py"
click node_prompt "https://github.com/cobanov/pydantic-agent-template/blob/main/app/agent/prompts.py"
click node_database "https://github.com/cobanov/pydantic-agent-template/blob/main/app/database.py"
click node_conversation "https://github.com/cobanov/pydantic-agent-template/blob/main/app/models.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_application,node_chat,node_health,node_auth,node_schemas,node_version,node_client toneBlue
class node_agentdeps,node_agentcore,node_prompt toneAmber
class node_database,node_conversation toneMint
class node_llm toneIndigo
```

## Components

### API

- [FastAPI app](https://github.com/cobanov/pydantic-agent-template/blob/main/app/main.py): `app/main.py`
- [Chat route](https://github.com/cobanov/pydantic-agent-template/blob/main/app/routers/chat.py): `app/routers/chat.py`
- [Health route](https://github.com/cobanov/pydantic-agent-template/blob/main/app/health.py): `app/health.py`
- [API-key check](https://github.com/cobanov/pydantic-agent-template/blob/main/app/auth.py): `app/auth.py`
- [API schemas](https://github.com/cobanov/pydantic-agent-template/blob/main/app/schemas.py): `app/schemas.py`
- [Version config](https://github.com/cobanov/pydantic-agent-template/blob/main/app/config.py): `app/config.py`

### Agent

- [Agent dependencies](https://github.com/cobanov/pydantic-agent-template/blob/main/app/agent/context.py): `app/agent/context.py`
- [Pydantic AI agent](https://github.com/cobanov/pydantic-agent-template/blob/main/app/agent/core.py): `app/agent/core.py`
- [System prompt](https://github.com/cobanov/pydantic-agent-template/blob/main/app/agent/prompts.py): `app/agent/prompts.py`

### Database

- [Async database](https://github.com/cobanov/pydantic-agent-template/blob/main/app/database.py): `app/database.py`
- [Conversation model](https://github.com/cobanov/pydantic-agent-template/blob/main/app/models.py): `app/models.py`

### Other components

- **HTTP client**
- **OpenAI model**

## Connections

- HTTP client → Chat route: sends request (evidence: `app/routers/chat.py`)
- Chat route → API-key check: checks key (evidence: `app/routers/chat.py`)
- Chat route → Agent dependencies: creates dependencies (evidence: `app/routers/chat.py`)
- Chat route → Pydantic AI agent: runs agent (evidence: `app/routers/chat.py`)
- Chat route → API schemas: uses request/response (evidence: `app/routers/chat.py`)
- Pydantic AI agent → Agent dependencies: declares dependency type (evidence: `app/agent/core.py`)
- Pydantic AI agent → System prompt: sets system prompt (evidence: `app/agent/core.py`)
- Pydantic AI agent → OpenAI model: configures model (evidence: `app/agent/core.py`)
- FastAPI app → Chat route: registers route (evidence: `app/main.py`)
- FastAPI app → Health route: registers route (evidence: `app/main.py`)
- FastAPI app → Async database: creates tables (evidence: `app/main.py`)
- FastAPI app → Conversation model: imports metadata model (evidence: `app/main.py`)
- Health route → API schemas: returns health schema (evidence: `app/health.py`)
- Health route → Version config: uses version (evidence: `app/health.py`)
- Async database → Conversation model: provides model base (evidence: `app/models.py`)
