# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Backend (Python / FastAPI)
- **Install dependencies**: `make install` (runs `uv sync`)
- **Run backend (dev)**: `make run` (runs `uv run python -m backend.main` with reload)
- **Setup environment**: `make setup` (copies `.env.example` to `.env` and runs the app)

### Frontend (React / Vite / Bun)
- **Install dependencies**: `make frontend-install` (runs `bun install`)
- **Run dev server**: `make frontend-dev` (runs `bun run dev`)
- **Build production**: `make frontend-build` (runs `bun run build`)

### Orchestration & Containers
- **Start all services**: `make compose-up` (Docker/Podman compose)
- **Follow logs**: `make compose-logs`
- **Stop all services**: `make compose-down`
- **Force rebuild images**: `make compose-rebuild`

### Maintenance
- **Clean artifacts**: `make clean`

## Architecture & Structure

### Big Picture Overview
Agent Alpha is a full-stack agentic AI application consisting of a FastAPI backend, a React frontend, and a RAG (Retrieval-Augmented Generation) pipeline. It utilizes **pydantic-ai** for agent logic and **uv** for Python dependency management.

### Backend Architecture (`/backend`)
The backend follows a layered architecture:
- **Core (`/backend/core`)**: The heart of the application. Contains configuration (`config.py`), database engine initialization (`database.py`), ORM models (`models.py`), and the primary agent lifecycle/inference logic (`agent.py`).
    - `AgentService` is a thin orchestrator that receives a pre-built `Agent` via constructor injection (wired at startup in `app.py`'s lifespan).
- **Database & Repositories**: 
    - **Models**: SQL Alchemy ORM models are split between general domain models (in `core`) and RAG-specific models (in `db/models` like `ChatFile`, `RagDocument`).
    - **Repositories**: Abstracted CRUD operations for all DB models are located in `/backend/repositories`. `MemoryRepository` encapsulates filesystem persistence for agent memories via `LocalBackend`.
- **RAG Pipeline (`/backend/rag`)**: Handles the document ingestion lifecycle. 
    - `connectors.py` manages sync sources.
    - `ingestion.py` manages the Parse → Chunk → Embed → Store pipeline.
    - `retrieval.py` and `reranker.py` handle multi-stage vector search and scoring.
    - `vectorstore.py` interfaces with Milvus.
- **Services**: Domain-specific logic for file storage, RAG tracking, status streaming (via Redis/SSE), and synchronization.
    - `agent_factory.py` provides `build_agent()` — a factory that wires model providers, Logfire, capabilities (`CodeMode`, `ToolSearch`, `MCP`, `WebSearch`, `InputGuard`, `ToolGuard`), subagents, skills, and RAG tools into a `pydantic-ai` agent.
    - `rag_service.py` provides `RagService` which builds RAG search tools for document retrieval.
- **Routes & Schemas**: FastAPI endpoints (`/routes`) are paired with Pydantic models (`/schemas`) for request validation and response serialization.
- **Worker**: Handles asynchronous tasks (like heavy RAG ingestion) via an in-process dispatcher, designed to eventually move to a Redis-backed ARQ setup.

### Frontend Architecture (`/frontend`)
A modern React SPA built with Vite and Tailwind CSS.
- **Core Components**: `App.tsx` handles routing between the main chat UI, the Admin dashboard, and the RAG management dashboard.
- **API Client**: Centralized API interaction logic in `api.ts`.
- **State & Proxy**: The dev server proxies `/api/*` requests to the FastAPI backend.

### Skills (`/skills`)
Modular agent capabilities are defined as "Skills". Each skill contains its own instructions and logic, allowing the main agent to dynamically expand its toolkit (e.g., financial analysis, brand guidelines).

## Key Patterns
- **Async First**: Most backend operations use `async/await` for database access and external API calls.
- **Dependency Injection**: Used extensively in FastAPI routes via the `dependencies.py` module.
- **RAG Flow**: Document Upload $\rightarrow$ Validation $\rightarrow$ Persistence $\rightarrow$ Parsing $\rightarrow$ Chunking $\rightarrow$ Embedding $\rightarrow$ Milvus Storage.