# farballo/agent-forge architecture

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

- Interactive diagram: https://gitdiagram.com/farballo/agent-forge
- Repository: https://github.com/farballo/agent-forge

## Overview

1. **System shape**
   - This repo is a multi-runtime assistant platform with three user-facing surfaces: a **FastAPI backend**, a **React/Vite SPA**, and a **Chainlit chat app**.
   - The backend is the system of record for users, agents, documents, auth, and tool metadata; Chainlit is the dedicated chat runtime; the frontend is the administrative UI.

2. **Backend request boundary**
   - `main.py` bootstraps the FastAPI app.
   - API routes live under `app/routers/` and are split by concern: `auth`, `agents`, `documents`, and `tools`.
   - The router layer is thin; it delegates to services rather than talking directly to storage.

3. **Application/service layer**
   - `app/services/` contains the business workflows:
     - `auth_service.py` handles registration and login.
     - `agent_service.py` manages agent CRUD and the agent’s vector-store lifecycle.
     - `ingestion_service.py` turns uploaded content into embeddings and stored chunks.
     - `retrieval_service.py` performs Chroma-backed retrieval for chat.
   - This is the main orchestration boundary between HTTP, database persistence, and vector search.

4. **Persistence layer**
   - `app/db/connection.py` wraps PostgreSQL access with a connection context manager.
   - `app/db/migrations.py` creates/updates tables on startup, so schema initialization is part of app boot.
   - Repositories in `app/repositories/` isolate SQL for users, agents, and documents, keeping DB concerns out of the services.

5. **Domain model**
   - Pydantic models in `app/models/` define the data contracts for users, agents, and documents.
   - These models are the shape of data moving across the API, services, and the frontend API layer.
   - The architecture is centered around the **agent** as the main tenant-scoped unit: users own agents, agents own documents, and agents determine chat behavior.

6. **Authentication and authorization**
   - `app/core/security.py` provides JWT and password hashing.
   - `app/core/dependencies.py` injects authenticated users, database connections, and user-scoped agent access into endpoints.
   - Access control is enforced server-side so both the REST API and Chainlit app can share the same user identity model.

7. **RAG and document pipeline**
   - Uploaded files and URL content are ingested through `ingestion_service.py`.
   - The pipeline is: **parse → chunk → embed → persist**.
   - Raw uploads are stored under `storage/uploads/`, while vector data is persisted under `storage/vectorstore/` using **ChromaDB**.
   - `retrieval_service.py` is the read side of this pipeline, fetching relevant context for chat responses.

8. **LLM and agent runtime**
   - The platform uses **LangChain** to abstract model providers, with per-agent support for **OpenAI** or **Anthropic**.
   - Provider choice is an agent-level concern, so the chat layer can route requests differently depending on which agent is active.
   - **LangSmith** tracing is an external observability dependency controlled by environment configuration.

9. **Chainlit chat subsystem**
   - `app/chainlit_app/` is a separate runtime for conversational interaction, with its own handlers, request context, runtime setup, and data layer.
   - It reads the same platform auth/session state and filters threads by **authenticated user** and **selected agent**.
   - This subsystem is the streaming/chat UI for the RAG assistant, distinct from the administrative React dashboard.

10. **Tooling subsystem**
   - `app/tools/db_query.py` and `app/tools/registry.py` define a factory for read-only PostgreSQL query tools bound to a specific `schema.table`.
   - Tools expose schema inspection, value sampling, and constrained querying, and they are surfaced in the UI with metadata.
   - This is a second data-access path besides RAG: agents can either retrieve from Chroma or inspect structured SQL data through controlled tools.

11. **Frontend boundary**
   - `frontend/` is a standalone React + TypeScript app built with Vite.
   - It consumes the backend API through `src/api/auth.ts` and `src/api/agents.ts`, then renders dashboard, agent management, tools, login, and registration pages.
   - UI state is split into reusable shell/components/contexts, with local storage utilities for client-side session or preference handling.

12. **Shared assets and deployment/runtime concerns**
   - `public/` contains browser-facing assets used by the app and Chainlit styling/customization.
   - `.chainlit/` config and translations indicate Chainlit’s UI is internationalized and configured separately from the React app.
   - The repo is designed for local multi-port execution: FastAPI on one port, Chainlit on another, and the frontend dev server on a third.

13. **Testing and reference material**
   - `tests/` covers auth, agents, ingestion, Chainlit request context/data layer/runtime behavior, and thread filtering.
   - `example_graph/` contains notebook-based graph experiments, which appear exploratory/reference rather than part of the core runtime.

14. **Main architectural flow**
   - A user registers/logs in through the backend, creates an agent, uploads documents, and optionally enables SQL tools.
   - The backend persists metadata in PostgreSQL and knowledge chunks in ChromaDB.
   - The Chainlit app uses the active agent to retrieve context, invoke tools if enabled, and stream LLM responses back to the user.

Main entry points: [`app/routers`](https://github.com/farballo/agent-forge/tree/main/app/routers) (API routers), [`app/services/ingestion_service.py`](https://github.com/farballo/agent-forge/blob/main/app/services/ingestion_service.py) (Ingest svc), [`app/chainlit_app/handlers.py`](https://github.com/farballo/agent-forge/blob/main/app/chainlit_app/handlers.py) (Chat handlers), [`app/db`](https://github.com/farballo/agent-forge/tree/main/app/db) (Postgres)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_main(("App boot<br/>FastAPI entrypoint<br/>[main.py]"))
  node_routers["API routers<br/>HTTP boundary"]
  node_services["Services<br/>workflow layer"]
  node_auth_service["Auth svc<br/>login and signup<br/>[auth_service.py]"]
  node_agent_service["Agent svc<br/>agent lifecycle<br/>[agent_service.py]"]
  node_ingestion_service["Ingest svc<br/>RAG ingestion"]
  node_retrieval_service["Retrieval svc<br/>context fetch"]
  node_db[("Postgres<br/>database layer")]
  node_repositories["Repositories<br/>SQL access"]
  node_models["Domain models<br/>Pydantic contracts"]
  node_security["Security<br/>auth utils<br/>[security.py]"]
  node_dependencies["Dependencies<br/>request injection<br/>[dependencies.py]"]
  node_tools["Tools<br/>sql tool layer"]
end

subgraph group_chat["Chat runtime"]
  node_chainlit_runtime(("Chainlit app<br/>chat runtime"))
  node_chainlit_data["Chat data<br/>session store<br/>[data_layer.py]"]
  node_chainlit_handlers["Chat handlers<br/>message flow<br/>[handlers.py]"]
  node_chainlit_context["Request context<br/>chat context<br/>[request_context.py]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app(("SPA<br/>React/Vite app"))
  node_frontend_api["API client<br/>REST client"]
  node_frontend_pages["Pages<br/>UI views"]
  node_frontend_shell["UI shell<br/>layout and state"]
end

node_main -->|"mounts"| node_routers
node_main -->|"initializes"| node_db
node_routers -->|"uses"| node_auth_service
node_routers -->|"uses"| node_agent_service
node_routers -->|"uses"| node_ingestion_service
node_routers -->|"uses"| node_tools
node_services -->|"persists via"| node_repositories
node_repositories -->|"queries"| node_db
node_services -->|"shape data"| node_models
node_dependencies -->|"relies on"| node_security
node_dependencies -->|"injects"| node_db
node_agent_service -->|"binds"| node_tools
node_ingestion_service -->|"feeds"| node_retrieval_service
node_ingestion_service -->|"stores metadata"| node_db
node_ingestion_service -.->|"powers"| node_chainlit_runtime
node_chainlit_runtime -->|"reads"| node_chainlit_context
node_chainlit_runtime -->|"dispatches"| node_chainlit_handlers
node_chainlit_handlers -->|"filters by"| node_chainlit_data
node_chainlit_handlers -->|"retrieves from"| node_retrieval_service
node_chainlit_handlers -->|"invokes"| node_tools
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_app -->|"shares"| node_frontend_shell
node_frontend_api -.->|"targets"| node_routers

click node_main "https://github.com/farballo/agent-forge/blob/main/main.py"
click node_routers "https://github.com/farballo/agent-forge/tree/main/app/routers"
click node_services "https://github.com/farballo/agent-forge/tree/main/app/services"
click node_auth_service "https://github.com/farballo/agent-forge/blob/main/app/services/auth_service.py"
click node_agent_service "https://github.com/farballo/agent-forge/blob/main/app/services/agent_service.py"
click node_ingestion_service "https://github.com/farballo/agent-forge/blob/main/app/services/ingestion_service.py"
click node_retrieval_service "https://github.com/farballo/agent-forge/blob/main/app/services/retrieval_service.py"
click node_db "https://github.com/farballo/agent-forge/tree/main/app/db"
click node_repositories "https://github.com/farballo/agent-forge/tree/main/app/repositories"
click node_models "https://github.com/farballo/agent-forge/tree/main/app/models"
click node_security "https://github.com/farballo/agent-forge/blob/main/app/core/security.py"
click node_dependencies "https://github.com/farballo/agent-forge/blob/main/app/core/dependencies.py"
click node_tools "https://github.com/farballo/agent-forge/tree/main/app/tools"
click node_chainlit_runtime "https://github.com/farballo/agent-forge/tree/main/app/chainlit_app"
click node_chainlit_data "https://github.com/farballo/agent-forge/blob/main/app/chainlit_app/data_layer.py"
click node_chainlit_handlers "https://github.com/farballo/agent-forge/blob/main/app/chainlit_app/handlers.py"
click node_chainlit_context "https://github.com/farballo/agent-forge/blob/main/app/chainlit_app/request_context.py"
click node_frontend_app "https://github.com/farballo/agent-forge/tree/main/frontend/src"
click node_frontend_api "https://github.com/farballo/agent-forge/tree/main/frontend/src/api"
click node_frontend_pages "https://github.com/farballo/agent-forge/tree/main/frontend/src/pages"
click node_frontend_shell "https://github.com/farballo/agent-forge/tree/main/frontend/src/components"

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_main,node_routers,node_services,node_auth_service,node_agent_service,node_ingestion_service,node_retrieval_service,node_db,node_repositories,node_models,node_security,node_dependencies,node_tools toneBlue
class node_chainlit_runtime,node_chainlit_data,node_chainlit_handlers,node_chainlit_context toneAmber
class node_frontend_app,node_frontend_api,node_frontend_pages,node_frontend_shell toneMint
```

## Components

### Backend

FastAPI API, services, persistence, and shared runtime logic.

- [App boot](https://github.com/farballo/agent-forge/blob/main/main.py): FastAPI entrypoint · Starts the backend app and wires startup behavior. · `main.py`
- [API routers](https://github.com/farballo/agent-forge/tree/main/app/routers): HTTP boundary · Thin REST layer for auth, agents, documents, and tools. · `app/routers`
- [Services](https://github.com/farballo/agent-forge/tree/main/app/services): workflow layer · Business orchestration for auth, agents, ingestion, and retrieval. · `app/services`
- [Auth svc](https://github.com/farballo/agent-forge/blob/main/app/services/auth_service.py): login and signup · Handles registration, login, and identity workflows. · `app/services/auth_service.py`
- [Agent svc](https://github.com/farballo/agent-forge/blob/main/app/services/agent_service.py): agent lifecycle · Manages agent CRUD and vector-store lifecycle. · `app/services/agent_service.py`
- [Ingest svc](https://github.com/farballo/agent-forge/blob/main/app/services/ingestion_service.py): RAG ingestion · Parses, chunks, embeds, and persists uploaded content. · `app/services/ingestion_service.py`
- [Retrieval svc](https://github.com/farballo/agent-forge/blob/main/app/services/retrieval_service.py): context fetch · Runs Chroma-backed retrieval for chat context. · `app/services/retrieval_service.py`
- [Postgres](https://github.com/farballo/agent-forge/tree/main/app/db): database layer · Connection and migration boundary for relational persistence. · `app/db`
- [Repositories](https://github.com/farballo/agent-forge/tree/main/app/repositories): SQL access · User, agent, and document repositories isolate SQL from services. · `app/repositories`
- [Domain models](https://github.com/farballo/agent-forge/tree/main/app/models): Pydantic contracts · Data contracts for users, agents, and documents. · `app/models`
- [Security](https://github.com/farballo/agent-forge/blob/main/app/core/security.py): auth utils · JWT and password hashing utilities. · `app/core/security.py`
- [Dependencies](https://github.com/farballo/agent-forge/blob/main/app/core/dependencies.py): request injection · Injects authenticated users, DB connections, and agent-scoped access. · `app/core/dependencies.py`
- [Tools](https://github.com/farballo/agent-forge/tree/main/app/tools): sql tool layer · Read-only PostgreSQL query tools and registry for agents. · `app/tools`

### Chat runtime

Chainlit conversational runtime and session/data handling.

- [Chainlit app](https://github.com/farballo/agent-forge/tree/main/app/chainlit_app): chat runtime · Separate conversational runtime for streaming chat interactions. · `app/chainlit_app`
- [Chat data](https://github.com/farballo/agent-forge/blob/main/app/chainlit_app/data_layer.py): session store · Synchronizes Chainlit threads with authenticated user and selected agent. · `app/chainlit_app/data_layer.py`
- [Chat handlers](https://github.com/farballo/agent-forge/blob/main/app/chainlit_app/handlers.py): message flow · Coordinates request handling, runtime behavior, and chat events. · `app/chainlit_app/handlers.py`
- [Request context](https://github.com/farballo/agent-forge/blob/main/app/chainlit_app/request_context.py): chat context · Carries platform identity and agent selection into chat requests. · `app/chainlit_app/request_context.py`

### Frontend

React/Vite administrative UI.

- [SPA](https://github.com/farballo/agent-forge/tree/main/frontend/src): React/Vite app · Standalone administrative UI for managing agents, tools, and auth. · `frontend/src`
- [API client](https://github.com/farballo/agent-forge/tree/main/frontend/src/api): REST client · Frontend calls into backend auth and agent endpoints. · `frontend/src/api`
- [Pages](https://github.com/farballo/agent-forge/tree/main/frontend/src/pages): UI views · Dashboard, landing, auth, agent, and tools screens. · `frontend/src/pages`
- [UI shell](https://github.com/farballo/agent-forge/tree/main/frontend/src/components): layout and state · Shared shell, components, contexts, and local storage utilities. · `frontend/src/components`

## Connections

- App boot → API routers: mounts · Bootstraps the HTTP API and exposes route modules.
- App boot → Postgres: initializes · Creates or updates schema on startup.
- API routers → Auth svc: uses · Auth routes delegate to service workflows.
- API routers → Agent svc: uses · Agent routes delegate to service workflows.
- API routers → Ingest svc: uses · Document routes hand off ingestion work.
- API routers → Tools: uses · Tool routes expose tool metadata and access.
- Services → Repositories: persists via · Services isolate SQL through repositories.
- Repositories → Postgres: queries · Repositories execute SQL through the connection layer.
- Services → Domain models: shape data · Domain models define payloads moving through the service layer.
- Dependencies → Security: relies on · Dependency helpers enforce auth and access control.
- Dependencies → Postgres: injects · Supplies database connections to endpoints and services.
- Agent svc → Tools: binds · Agents can be associated with structured query tools.
- Ingest svc → Retrieval svc: feeds · Embedded chunks become retrievable chat context.
- Ingest svc → Postgres: stores metadata · Document and agent metadata persist in PostgreSQL.
- Ingest svc → Chainlit app: powers · Ingested knowledge is consumed by the chat runtime.
- Chainlit app → Request context: reads · Chat sessions use shared user and agent context.
- Chainlit app → Chat handlers: dispatches · Runtime events are handled by chat handlers.
- Chat handlers → Chat data: filters by · Threads are scoped to authenticated users and selected agents.
- Chat handlers → Retrieval svc: retrieves from · Chat responses pull relevant context from Chroma.
- Chat handlers → Tools: invokes · Enabled agents can call read-only SQL tools.
- SPA → API client: calls · UI pages consume backend authentication and agent APIs.
- SPA → Pages: renders · App composes the main screens and navigation.
- SPA → UI shell: shares · Common layout, components, and client state live here.
- API client → API routers: targets · Frontend API clients map to backend route surface.