Files

Yunxiao Xu b4f79ee052 docs: update project documentation and verification strategies

- Update GEMINI.md with verification steps and remove ignored docs reference
- Update README.md to remove reference to local langchain-docs
- Update backend/GEMINI.md with correct database schema (users table) and architecture details
- Update frontend/GEMINI.md with latest project structure

2026-02-20 17:14:16 -08:00

3.7 KiB

Raw Permalink Blame History

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

README: Main project documentation and setup guide.
Backend Guide: Detailed information about the backend architecture, migration goals, and implementation steps.
Frontend Guide: Frontend development guide and technology stack.

Verification Strategy

When making changes, always verify using the following commands:

Backend

Test: cd backend && uv run pytest
Lint/Format: cd backend && uv run ruff check .
Type Check: cd backend && uv run mypy . (if configured)

Frontend

Test: cd frontend && npm run test
Lint: cd frontend && npm run lint
Build: cd frontend && npm run build (to ensure no compilation errors)

Git Operations

All new feature and bug-fix branches must be created from the develop branch except hot-fix.
The develop branch serves as the primary development branch where integration occurs.
The main branch is reserved for stable, production-ready code.
Merges from develop to main should only occur when significant milestones are reached and stability is verified.
CRITICAL: Conductor-specific configuration or meta-files (e.g., conductor/ directory) must NEVER be tracked or committed to the repository. They are intended for local agent guidance and coordination only.
Use rebase to keep commit history clean before merging feature branches back into develop.

3.7 KiB Raw Permalink Blame History