# Election Analytics Chatbot

## Overview
This project is an Election Analytics Chatbot built with a modern, stateful, and graph-based architecture. It is divided into a backend (Python, LangGraph) and a frontend (React, TypeScript).

## Project Structure
- **[Backend](./backend/GEMINI.md)**: Python-based LangGraph agent for data analysis and query processing.
- **[Frontend](./frontend/GEMINI.md)**: React application for user interaction.

## Key Technologies
- **Backend**: LangGraph, LangChain, OpenAI/Google Gemini, PostgreSQL, FastAPI.
- **Frontend**: React, TypeScript, Vite, Tailwind CSS, Shadcn UI.

## Backend API (`/api/v1`)
The backend provides a versioned REST and Streaming API:

### Authentication (`/auth`)
- `POST /register`: New user registration.
- `POST /login`: Email/password login setting an `access_token` HttpOnly cookie.
- `POST /logout`: Clears the authentication cookie.
- `GET /me`: Returns the current authenticated user's profile.
- `GET /oidc/login` & `/oidc/callback`: Full OIDC/SSO integration.

### Agent execution (`/chat`)
- `POST /stream`: A stateful SSE (Server-Sent Events) endpoint that streams the LangGraph agent's reasoning steps, model chunks, and generated plots in real-time.

### History Management (`/conversations`)
- `GET /`: List all conversations for the current user.
- `POST /`: Create a new conversation.
- `GET /{id}/messages`: Retrieve full message history including step-by-step reasoning.
- `PATCH /{id}`: Rename or update conversation summaries.
- `DELETE /{id}`: Persistent deletion of chat history.

### Artifacts (`/artifacts`)
- `GET /plots/{plot_id}`: Secure binary retrieval of generated analysis charts (PNG).

## Frontend Architecture
The frontend is a modern SPA (Single Page Application) designed for data-heavy interactions:

- **State Management**: React-based state with Axios interceptors for automatic session handling (401 redirects).
- **Authentication**: Seamlessly handles both traditional and OIDC login flows, persisting sessions via browser-native cookie handling.
- **UI System**: Built with Shadcn UI and Tailwind CSS, featuring a responsive sidebar-based layout for conversation management.
- **Real-time Visualization**: Supports streaming text responses and immediate rendering of base64-encoded or binary-retrieved analysis plots.

## Documentation
- **[Backend Guide](./backend/GEMINI.md)**: Detailed information about the backend architecture, migration goals, and implementation steps.
- **[Frontend Guide](./frontend/GEMINI.md)**: Frontend development guide and technology stack.
- **LangChain Docs**: See the `langchain-docs/` folder for local LangChain and LangGraph documentation.

## Git Operations
- Branches should be used for specific features or bug fixes.
- New branches should be created from the `main` branch and `conductor` branch.
- The conductor should always use the `conductor` branch and derived branches.
- When a feature or fix is complete, use rebase to keep the commit history clean before merging.
- The conductor related changes should never be merged into the `main` branch.