ea-chatbot-lg/GEMINI.md

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: Python-based LangGraph agent for data analysis and query processing.
• Frontend: 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: Detailed information about the backend architecture, migration goals, and implementation steps.
• Frontend Guide: 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.