b4f79ee052
- 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
70 lines
3.7 KiB
Markdown
70 lines
3.7 KiB
Markdown
# 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
|
|
- **[README](./README.md)**: Main project documentation and setup guide.
|
|
- **[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.
|
|
|
|
## 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`.
|