# assada/agent_template architecture

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

- Interactive diagram: https://gitdiagram.com/assada/agent_template
- Repository: https://github.com/assada/agent_template

## Overview

This repository is a FastAPI template that serves configurable LangGraph agents. The main workflow accepts an authenticated HTTP request, routes it through the thread controller, creates or retrieves a thread, builds the configured agent, and streams its response as SSE. Separate branches provide thread history and feedback, while user/thread persistence, prompt resolution, checkpointing, and Langfuse tracing support the agent runtime. Relationships are limited to excerpted calls, SOURCE INDEX references, or README capabilities; several agent internals are indexed but unsampled.

Main entry points: [`app/agent/factory.py`](https://github.com/assada/agent_template/blob/master/app/agent/factory.py) (Agent factory), [`app/http/controllers/thread_controller.py`](https://github.com/assada/agent_template/blob/master/app/http/controllers/thread_controller.py) (Thread controller), [`app/agent/langgraph/langgraph_agent_instance.py`](https://github.com/assada/agent_template/blob/master/app/agent/langgraph/langgraph_agent_instance.py) (Agent execution), [`app/http/routes/thread_routes.py`](https://github.com/assada/agent_template/blob/master/app/http/routes/thread_routes.py) (HTTP routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP and identity"]
  node_routes["HTTP routes<br/>[thread_routes.py]"]
  node_auth["Token authentication<br/>[auth.py]"]
  node_user_service["User service<br/>[user_service.py]"]
end

subgraph group_threads["Thread management"]
  node_controller["Thread controller"]
  node_thread_service["Thread service<br/>[thread_service.py]"]
  node_thread_repo["Thread repository"]
  node_thread_model["Thread record<br/>[thread.py]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_registry["Agent registry<br/>[agent_registry.py]"]
  node_agent_factory["Agent factory<br/>[factory.py]"]
  node_agent_config["Agent configuration<br/>[config.py]"]
  node_prompt_resolver["Prompt resolver<br/>[prompt_resolver.py]"]
  node_prompt["Prompt providers<br/>[prompt.py]"]
  node_graph["LangGraph builder<br/>[graph.py]"]
  node_agent_instance["Agent execution"]
  node_stream_processor["SSE stream processor"]
  node_agent_service["Feedback and tracing<br/>[agent_service.py]"]
end

subgraph group_data["Persistence and checkpoints"]
  node_user_repo["User repository<br/>[user_repository.py]"]
  node_user_model["User record<br/>[user.py]"]
  node_checkpointer_resolver["Checkpoint resolver<br/>[resolver.py]"]
  node_memory_checkpoint["Memory checkpoint<br/>[memory.py]"]
  node_postgres_checkpoint["Postgres checkpoint<br/>[postgres.py]"]
  node_session["Session manager<br/>[session.py]"]
end

node_client(("API client"))
node_langfuse["Langfuse"]
node_database[("PostgreSQL")]

node_client -->|"sends requests"| node_routes
node_routes -->|"requires identity"| node_auth
node_routes -->|"manages threads"| node_thread_service
node_routes -->|"delegates history"| node_controller
node_controller -->|"creates or updates"| node_thread_service
node_controller -->|"creates agent"| node_agent_factory
node_controller -->|"streams or loads"| node_agent_instance
node_controller -->|"records feedback"| node_agent_service
node_auth -->|"resolves user"| node_user_service
node_thread_service -->|"delegates operations"| node_thread_repo
node_thread_repo -->|"queries and persists"| node_session
node_thread_repo -->|"reads and writes"| node_thread_model
node_user_service -->|"delegates lookup"| node_user_repo
node_user_repo -->|"queries users"| node_session
node_user_repo -->|"loads records"| node_user_model
node_agent_registry -->|"registers agents"| node_agent_factory
node_agent_factory -->|"uses settings"| node_agent_config
node_agent_factory -->|"resolves prompts"| node_prompt_resolver
node_prompt_resolver -.->|"selects provider"| node_prompt
node_agent_factory -->|"selects checkpoint"| node_checkpointer_resolver
node_agent_factory -.->|"builds graph"| node_graph
node_agent_factory -->|"wraps compiled graph"| node_agent_instance
node_agent_instance -->|"processes stream"| node_stream_processor
node_agent_instance -->|"uses thread state"| node_thread_model
node_checkpointer_resolver -.->|"selects backend"| node_memory_checkpoint
node_checkpointer_resolver -.->|"selects backend"| node_postgres_checkpoint
node_postgres_checkpoint -->|"stores checkpoints"| node_database
node_session -.->|"opens sessions"| node_database
node_agent_service -.->|"tracks feedback"| node_langfuse
node_agent_instance -.->|"traces runs"| node_langfuse

click node_routes "https://github.com/assada/agent_template/blob/master/app/http/routes/thread_routes.py"
click node_auth "https://github.com/assada/agent_template/blob/master/app/http/middleware/auth.py"
click node_controller "https://github.com/assada/agent_template/blob/master/app/http/controllers/thread_controller.py"
click node_thread_service "https://github.com/assada/agent_template/blob/master/app/services/thread_service.py"
click node_thread_repo "https://github.com/assada/agent_template/blob/master/app/repositories/thread_repository.py"
click node_thread_model "https://github.com/assada/agent_template/blob/master/app/models/thread.py"
click node_user_service "https://github.com/assada/agent_template/blob/master/app/services/user_service.py"
click node_user_repo "https://github.com/assada/agent_template/blob/master/app/repositories/user_repository.py"
click node_user_model "https://github.com/assada/agent_template/blob/master/app/models/user.py"
click node_agent_registry "https://github.com/assada/agent_template/blob/master/app/bootstrap/agent_registry.py"
click node_agent_factory "https://github.com/assada/agent_template/blob/master/app/agent/factory.py"
click node_agent_config "https://github.com/assada/agent_template/blob/master/app/agent/config.py"
click node_prompt_resolver "https://github.com/assada/agent_template/blob/master/app/agent/prompt_resolver.py"
click node_prompt "https://github.com/assada/agent_template/blob/master/app/agent/prompt.py"
click node_graph "https://github.com/assada/agent_template/blob/master/app/agent/langgraph/graph.py"
click node_agent_instance "https://github.com/assada/agent_template/blob/master/app/agent/langgraph/langgraph_agent_instance.py"
click node_stream_processor "https://github.com/assada/agent_template/blob/master/app/agent/services/stream_processor.py"
click node_agent_service "https://github.com/assada/agent_template/blob/master/app/agent/services/agent_service.py"
click node_checkpointer_resolver "https://github.com/assada/agent_template/blob/master/app/agent/langgraph/checkpoint/resolver.py"
click node_memory_checkpoint "https://github.com/assada/agent_template/blob/master/app/agent/langgraph/checkpoint/memory.py"
click node_postgres_checkpoint "https://github.com/assada/agent_template/blob/master/app/agent/langgraph/checkpoint/postgres.py"
click node_session "https://github.com/assada/agent_template/blob/master/app/infrastructure/database/session.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_routes,node_auth,node_user_service,node_client toneBlue
class node_controller,node_thread_service,node_thread_repo,node_thread_model,node_database toneAmber
class node_agent_registry,node_agent_factory,node_agent_config,node_prompt_resolver,node_prompt,node_graph,node_agent_instance,node_stream_processor,node_agent_service toneMint
class node_user_repo,node_user_model,node_checkpointer_resolver,node_memory_checkpoint,node_postgres_checkpoint,node_session toneRose
class node_langfuse toneIndigo
```

## Components

### HTTP and identity

- [HTTP routes](https://github.com/assada/agent_template/blob/master/app/http/routes/thread_routes.py): `app/http/routes/thread_routes.py`
- [Token authentication](https://github.com/assada/agent_template/blob/master/app/http/middleware/auth.py): `app/http/middleware/auth.py`
- [User service](https://github.com/assada/agent_template/blob/master/app/services/user_service.py): `app/services/user_service.py`

### Thread management

- [Thread controller](https://github.com/assada/agent_template/blob/master/app/http/controllers/thread_controller.py): `app/http/controllers/thread_controller.py`
- [Thread service](https://github.com/assada/agent_template/blob/master/app/services/thread_service.py): `app/services/thread_service.py`
- [Thread repository](https://github.com/assada/agent_template/blob/master/app/repositories/thread_repository.py): `app/repositories/thread_repository.py`
- [Thread record](https://github.com/assada/agent_template/blob/master/app/models/thread.py): `app/models/thread.py`

### Agent runtime

- [Agent registry](https://github.com/assada/agent_template/blob/master/app/bootstrap/agent_registry.py): `app/bootstrap/agent_registry.py`
- [Agent factory](https://github.com/assada/agent_template/blob/master/app/agent/factory.py): `app/agent/factory.py`
- [Agent configuration](https://github.com/assada/agent_template/blob/master/app/agent/config.py): `app/agent/config.py`
- [Prompt resolver](https://github.com/assada/agent_template/blob/master/app/agent/prompt_resolver.py): `app/agent/prompt_resolver.py`
- [Prompt providers](https://github.com/assada/agent_template/blob/master/app/agent/prompt.py): `app/agent/prompt.py`
- [LangGraph builder](https://github.com/assada/agent_template/blob/master/app/agent/langgraph/graph.py): `app/agent/langgraph/graph.py`
- [Agent execution](https://github.com/assada/agent_template/blob/master/app/agent/langgraph/langgraph_agent_instance.py): `app/agent/langgraph/langgraph_agent_instance.py`
- [SSE stream processor](https://github.com/assada/agent_template/blob/master/app/agent/services/stream_processor.py): `app/agent/services/stream_processor.py`
- [Feedback and tracing](https://github.com/assada/agent_template/blob/master/app/agent/services/agent_service.py): `app/agent/services/agent_service.py`

### Persistence and checkpoints

- [User repository](https://github.com/assada/agent_template/blob/master/app/repositories/user_repository.py): `app/repositories/user_repository.py`
- [User record](https://github.com/assada/agent_template/blob/master/app/models/user.py): `app/models/user.py`
- [Checkpoint resolver](https://github.com/assada/agent_template/blob/master/app/agent/langgraph/checkpoint/resolver.py): `app/agent/langgraph/checkpoint/resolver.py`
- [Memory checkpoint](https://github.com/assada/agent_template/blob/master/app/agent/langgraph/checkpoint/memory.py): `app/agent/langgraph/checkpoint/memory.py`
- [Postgres checkpoint](https://github.com/assada/agent_template/blob/master/app/agent/langgraph/checkpoint/postgres.py): `app/agent/langgraph/checkpoint/postgres.py`
- [Session manager](https://github.com/assada/agent_template/blob/master/app/infrastructure/database/session.py): `app/infrastructure/database/session.py`

### Other components

- **API client**
- **Langfuse**
- **PostgreSQL**

## Connections

- API client → HTTP routes: sends requests (evidence: `app/http/routes/thread_routes.py`)
- HTTP routes → Token authentication: requires identity (evidence: `app/http/routes/thread_routes.py`)
- HTTP routes → Thread service: manages threads (evidence: `app/http/routes/thread_routes.py`)
- HTTP routes → Thread controller: delegates history (evidence: `app/http/routes/thread_routes.py`)
- Thread controller → Thread service: creates or updates (evidence: `app/http/controllers/thread_controller.py`)
- Thread controller → Agent factory: creates agent (evidence: `app/http/controllers/thread_controller.py`)
- Thread controller → Agent execution: streams or loads (evidence: `app/http/controllers/thread_controller.py`)
- Thread controller → Feedback and tracing: records feedback (evidence: `app/http/controllers/thread_controller.py`)
- Token authentication → User service: resolves user (evidence: `app/http/middleware/auth.py`)
- Thread service → Thread repository: delegates operations (evidence: `app/services/thread_service.py`)
- Thread repository → Session manager: queries and persists (evidence: `app/repositories/thread_repository.py`)
- Thread repository → Thread record: reads and writes (evidence: `app/repositories/thread_repository.py`)
- User service → User repository: delegates lookup (evidence: `app/services/user_service.py`)
- User repository → Session manager: queries users (evidence: `app/repositories/user_repository.py`)
- User repository → User record: loads records (evidence: `app/repositories/user_repository.py`)
- Agent registry → Agent factory: registers agents (evidence: `app/bootstrap/agent_registry.py`)
- Agent factory → Agent configuration: uses settings (evidence: `app/agent/factory.py`)
- Agent factory → Prompt resolver: resolves prompts (evidence: `app/agent/factory.py`)
- Prompt resolver → Prompt providers: selects provider
- Agent factory → Checkpoint resolver: selects checkpoint (evidence: `app/agent/factory.py`)
- Agent factory → LangGraph builder: builds graph
- Agent factory → Agent execution: wraps compiled graph (evidence: `app/agent/factory.py`)
- Agent execution → SSE stream processor: processes stream (evidence: `app/agent/langgraph/langgraph_agent_instance.py`)
- Agent execution → Thread record: uses thread state (evidence: `app/agent/langgraph/langgraph_agent_instance.py`)
- Checkpoint resolver → Memory checkpoint: selects backend
- Checkpoint resolver → Postgres checkpoint: selects backend
- Postgres checkpoint → PostgreSQL: stores checkpoints (evidence: `app/agent/langgraph/checkpoint/postgres.py`)
- Session manager → PostgreSQL: opens sessions
- Feedback and tracing → Langfuse: tracks feedback
- Agent execution → Langfuse: traces runs
