How farballo/agent-forge works
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: routers API routers · ingestion_service.py Ingest svc · handlers.py Chat handlers · db Postgres
Components 21
Backend
FastAPI API, services, persistence, and shared runtime logic.
- App boot · Starts the backend app and wires startup behavior.
main.py - API routers · Thin REST layer for auth, agents, documents, and tools.
app/routers - Services · Business orchestration for auth, agents, ingestion, and retrieval.
app/services - Auth svc · Handles registration, login, and identity workflows.
app/services/auth_service.py - Agent svc · Manages agent CRUD and vector-store lifecycle.
app/services/agent_service.py - Ingest svc · Parses, chunks, embeds, and persists uploaded content.
app/services/ingestion_service.py - Retrieval svc · Runs Chroma-backed retrieval for chat context.
app/services/retrieval_service.py - Postgres · Connection and migration boundary for relational persistence.
app/db - Repositories · User, agent, and document repositories isolate SQL from services.
app/repositories - Domain models · Data contracts for users, agents, and documents.
app/models - Security · JWT and password hashing utilities.
app/core/security.py - Dependencies · Injects authenticated users, DB connections, and agent-scoped access.
app/core/dependencies.py - Tools · Read-only PostgreSQL query tools and registry for agents.
app/tools
Chat runtime
Chainlit conversational runtime and session/data handling.
- Chainlit app · Separate conversational runtime for streaming chat interactions.
app/chainlit_app - Chat data · Synchronizes Chainlit threads with authenticated user and selected agent.
app/chainlit_app/data_layer.py - Chat handlers · Coordinates request handling, runtime behavior, and chat events.
app/chainlit_app/handlers.py - Request context · Carries platform identity and agent selection into chat requests.
app/chainlit_app/request_context.py
Frontend
React/Vite administrative UI.
- SPA · Standalone administrative UI for managing agents, tools, and auth.
frontend/src - API client · Frontend calls into backend auth and agent endpoints.
frontend/src/api - Pages · Dashboard, landing, auth, agent, and tools screens.
frontend/src/pages - UI shell · Shared shell, components, contexts, and local storage utilities.
frontend/src/components
Connections 24
- 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.