# wassim249/fastapi-langgraph-agent-production-ready-template architecture

> Architecture diagram of the GitHub repository wassim249/fastapi-langgraph-agent-production-ready-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/wassim249/fastapi-langgraph-agent-production-ready-template
- Repository: https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template

## Overview

This repository is a FastAPI backend template for stateful LangGraph AI agents. Its main workflow authenticates a user’s chat session, accepts a message, runs the agent with checkpointed conversation state and optional memory/tools, then returns or streams a response. Separate branches cover registration and session management, generated session titles, and production operations such as caching, rate limits, metrics, and tracing. The README also documents an evaluation framework. Some subsystem links rely on README or source-index references; unsampled implementation details are not inferred.

Main entry points: [`app/core/langgraph/graph.py`](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/langgraph/graph.py) (LangGraph agent), [`app/main.py`](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/main.py) (FastAPI application), [`app/api/v1/chatbot.py`](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/api/v1/chatbot.py) (Chat endpoints), [`app/services/database.py`](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/database.py) (Database service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_app["FastAPI application<br/>[main.py]"]
  node_routes["API router<br/>[api.py]"]
  node_auth["Auth and sessions<br/>[auth.py]"]
  node_jwt["JWT utilities<br/>[auth.py]"]
  node_chat["Chat endpoints<br/>[chatbot.py]"]
  node_schemas["Request schemas<br/>[chat.py]"]
end

subgraph group_agent["Agent runtime"]
  node_agentgraph["LangGraph agent<br/>[graph.py]"]
  node_tools["Agent tools"]
  node_llm["LLM service<br/>[service.py]"]
  node_registry["Model registry<br/>[registry.py]"]
  node_titles["Session naming<br/>[session_naming.py]"]
  node_llmprovider["LLM provider"]
end

subgraph group_data["Persistence and memory"]
  node_database["Database service<br/>[database.py]"]
  node_sessionmodel["Session model<br/>[session.py]"]
  node_user_model["User model<br/>[user.py]"]
  node_memory["Long-term memory<br/>[memory.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_operations["Operations"]
  node_cache["Cache service<br/>[cache.py]"]
  node_valkey[("Valkey or Redis")]
  node_middleware["Request middleware<br/>[middleware.py]"]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
  node_observability["Tracing and logging<br/>[observability.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evals["Evaluation framework<br/>[evaluator.py]"]
end

node_user(("API user"))

node_user -->|"sends requests"| node_app
node_app -->|"mounts router"| node_routes
node_routes -->|"routes auth"| node_auth
node_routes -->|"routes chat"| node_chat
node_auth -->|"uses tokens"| node_jwt
node_auth -->|"manages users and sessions"| node_database
node_database -->|"persists users"| node_user_model
node_database -->|"persists sessions"| node_sessionmodel
node_chat -->|"validates messages"| node_schemas
node_chat -->|"invokes agent"| node_agentgraph
node_chat -->|"may name session"| node_titles
node_agentgraph -->|"calls model service"| node_llm
node_agentgraph -->|"binds tools"| node_tools
node_agentgraph -->|"searches memory"| node_memory
node_agentgraph -->|"checkpoints state"| node_postgres
node_llm -->|"resolves models"| node_registry
node_registry -->|"creates provider models"| node_llmprovider
node_titles -->|"generates title"| node_llm
node_titles -->|"claims and updates session"| node_database
node_memory -->|"uses cache"| node_cache
node_cache -.->|"uses when configured"| node_valkey
node_app -->|"installs middleware"| node_middleware
node_middleware -->|"records request metrics"| node_metrics
node_app -->|"exposes metrics"| node_metrics
node_agentgraph -.->|"integrates tracing"| node_observability
node_evals -.->|"evaluates model outputs"| node_llmprovider

click node_app "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/main.py"
click node_routes "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/api/v1/api.py"
click node_auth "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/api/v1/auth.py"
click node_jwt "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/utils/auth.py"
click node_chat "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/api/v1/chatbot.py"
click node_schemas "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/schemas/chat.py"
click node_agentgraph "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/langgraph/graph.py"
click node_tools "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/tree/master/app/core/langgraph/tools"
click node_llm "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/llm/service.py"
click node_registry "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/llm/registry.py"
click node_titles "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/session_naming.py"
click node_database "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/database.py"
click node_sessionmodel "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/models/session.py"
click node_user_model "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/models/user.py"
click node_memory "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/memory.py"
click node_cache "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/cache.py"
click node_middleware "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/middleware.py"
click node_metrics "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/metrics.py"
click node_observability "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/observability.py"
click node_evals "https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/evals/evaluator.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_app,node_routes,node_auth,node_jwt,node_chat,node_schemas,node_user toneBlue
class node_agentgraph,node_tools,node_llm,node_registry,node_titles,node_llmprovider toneAmber
class node_database,node_sessionmodel,node_user_model,node_memory,node_postgres toneMint
class node_cache,node_valkey,node_middleware,node_metrics,node_observability toneRose
class node_evals toneIndigo
```

## Components

### API and identity

- [FastAPI application](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/main.py): `app/main.py`
- [API router](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/api/v1/api.py): `app/api/v1/api.py`
- [Auth and sessions](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/api/v1/auth.py): `app/api/v1/auth.py`
- [JWT utilities](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/utils/auth.py): `app/utils/auth.py`
- [Chat endpoints](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/api/v1/chatbot.py): `app/api/v1/chatbot.py`
- [Request schemas](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/schemas/chat.py): `app/schemas/chat.py`

### Agent runtime

- [LangGraph agent](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/langgraph/graph.py): `app/core/langgraph/graph.py`
- [Agent tools](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/tree/master/app/core/langgraph/tools): `app/core/langgraph/tools`
- [LLM service](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/llm/service.py): `app/services/llm/service.py`
- [Model registry](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/llm/registry.py): `app/services/llm/registry.py`
- [Session naming](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/session_naming.py): `app/services/session_naming.py`
- **LLM provider**

### Persistence and memory

- [Database service](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/database.py): `app/services/database.py`
- [Session model](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/models/session.py): `app/models/session.py`
- [User model](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/models/user.py): `app/models/user.py`
- [Long-term memory](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/services/memory.py): `app/services/memory.py`
- **PostgreSQL**

### Operations

- [Cache service](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/cache.py): `app/core/cache.py`
- **Valkey or Redis**
- [Request middleware](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/middleware.py): `app/core/middleware.py`
- [Prometheus metrics](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/metrics.py): `app/core/metrics.py`
- [Tracing and logging](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/app/core/observability.py): `app/core/observability.py`

### Evaluation

- [Evaluation framework](https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template/blob/master/evals/evaluator.py): `evals/evaluator.py`

### Other components

- **API user**

## Connections

- API user → FastAPI application: sends requests (evidence: `app/main.py`)
- FastAPI application → API router: mounts router (evidence: `app/main.py`)
- API router → Auth and sessions: routes auth (evidence: `app/api/v1/api.py`)
- API router → Chat endpoints: routes chat (evidence: `app/api/v1/api.py`)
- Auth and sessions → JWT utilities: uses tokens (evidence: `app/api/v1/auth.py`)
- Auth and sessions → Database service: manages users and sessions (evidence: `app/api/v1/auth.py`)
- Database service → User model: persists users (evidence: `app/services/database.py`)
- Database service → Session model: persists sessions (evidence: `app/services/database.py`)
- Chat endpoints → Request schemas: validates messages (evidence: `app/api/v1/chatbot.py`)
- Chat endpoints → LangGraph agent: invokes agent (evidence: `app/api/v1/chatbot.py`)
- Chat endpoints → Session naming: may name session (evidence: `app/api/v1/chatbot.py`)
- LangGraph agent → LLM service: calls model service (evidence: `app/core/langgraph/graph.py`)
- LangGraph agent → Agent tools: binds tools (evidence: `app/core/langgraph/graph.py`)
- LangGraph agent → Long-term memory: searches memory (evidence: `app/core/langgraph/graph.py`)
- LangGraph agent → PostgreSQL: checkpoints state (evidence: `app/core/langgraph/graph.py`)
- LLM service → Model registry: resolves models (evidence: `app/services/llm/service.py`)
- Model registry → LLM provider: creates provider models
- Session naming → LLM service: generates title (evidence: `app/services/session_naming.py`)
- Session naming → Database service: claims and updates session (evidence: `app/services/session_naming.py`)
- Long-term memory → Cache service: uses cache (evidence: `app/services/memory.py`)
- Cache service → Valkey or Redis: uses when configured (evidence: `app/core/cache.py`)
- FastAPI application → Request middleware: installs middleware (evidence: `app/main.py`)
- Request middleware → Prometheus metrics: records request metrics (evidence: `app/core/middleware.py`)
- FastAPI application → Prometheus metrics: exposes metrics (evidence: `app/main.py`)
- LangGraph agent → Tracing and logging: integrates tracing (evidence: `app/core/langgraph/graph.py`)
- Evaluation framework → LLM provider: evaluates model outputs
