# Election Analytics Chatbot - Backend Guide

## Overview
The backend is a Python-based FastAPI application that leverages **LangGraph** to provide a stateful, agentic workflow for election data analysis. It handles complex queries by decomposing them into tasks such as data analysis, web research, or user clarification.

## 1. Architecture Overview
- **Framework**: LangGraph for workflow orchestration and state management.
- **API**: FastAPI for providing REST and streaming (SSE) endpoints.
- **State Management**: Persistent state using LangGraph's `StateGraph` with a PostgreSQL checkpointer.
- **Database**: PostgreSQL.
  - Application data: Uses `users` table for local and OIDC users (String IDs).
  - History: Persists chat history and artifacts.
  - Election Data: Structured datasets for analysis.

## 2. Core Components

### 2.1. The Graph State (`src/ea_chatbot/graph/state.py`)
The state tracks the conversation context, plan, generated code, execution results, and artifacts.

### 2.2. Nodes (The Actors)
Located in `src/ea_chatbot/graph/nodes/`:

- **`query_analyzer`**: Analyzes the user query to determine the intent and required data.
- **`planner`**: Creates a step-by-step plan for data analysis.
- **`coder`**: Generates Python code based on the plan and dataset metadata.
- **`executor`**: Safely executes the generated code and captures outputs (dataframes, plots).
- **`error_corrector`**: Fixes code if execution fails.
- **`researcher`**: Performs web searches for general election information.
- **`summarizer`**: Generates a natural language response based on the analysis results.
- **`clarification`**: Asks the user for more information if the query is ambiguous.

### 2.3. The Workflow (Graph)
The graph connects these nodes with conditional edges, allowing for iterative refinement and error correction.

## 3. Key Modules

- **`src/ea_chatbot/api/`**: Contains FastAPI routers for authentication, conversation management, and the agent streaming endpoint.
- **`src/ea_chatbot/graph/`**: Core LangGraph logic, including state definitions, node implementations, and the workflow graph.
- **`src/ea_chatbot/history/`**: Manages persistent chat history and message mapping between application models and LangGraph state.
- **`src/ea_chatbot/utils/`**: Utility functions for database inspection, LLM factory, and logging.

## 4. Development & Execution

### Entry Point
The main entry point for the API is `src/ea_chatbot/api/main.py`.

### Running the API
```bash
cd backend
uv run python -m ea_chatbot.api.main
```

### Database Migrations
Handled by Alembic.
```bash
uv run alembic upgrade head
```

### Testing
Tests are located in the `tests/` directory and use `pytest`.
```bash
uv run pytest
```