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

2.7 KiB

Raw Blame History

Election Analytics Chatbot - Frontend Guide

Overview

This document serves as a guide for the frontend implementation of the Election Analytics Chatbot. The frontend is a modern React SPA designed for seamless user interaction and real-time data visualization.

Key Technologies

React 18+: For building the component-based UI.
TypeScript: Ensuring type safety across the codebase.
Vite: Modern build tool providing a fast development experience.
Tailwind CSS v4: Utility-first styling with the latest features.
Shadcn UI: High-quality, accessible UI components.
React Router: Client-side routing for authentication and main application views.
Axios: HTTP client for API communication, configured for cookie-based sessions.

Project Structure

src/components/:
- auth/: Login, Registration, and OIDC callback forms/pages.
- chat/: Core chat interface components, including message list and plot rendering.
- layout/: Main application layout including the sidebar navigation.
- ui/: Reusable primitive components (buttons, cards, inputs, etc.) via Shadcn.
src/services/:
- api.ts: Axios instance configuration with /api/v1 base URL and interceptors.
- auth.ts: Authentication logic (Login, Logout, OIDC, User Profile).
- chat.ts: Service for interacting with the agent streaming endpoint.
src/lib/:
- validations/: Zod schemas for form validation.
- utils.ts: Core utility functions.
src/hooks/: Custom React hooks (e.g., useIsMobile).

Authentication System

The frontend utilizes a secure, cookie-based authentication strategy:

HttpOnly Cookies: JWT tokens are stored in access_token cookies, protected from XSS.
Axios Configuration: withCredentials: true is enabled to ensure cookies are sent with every request.
401 Interceptor: A global response interceptor automatically handles session expiration by redirecting to the login view.
OIDC/SSO: Supports OAuth2/OpenID Connect flows with a dedicated /auth/callback route for token exchange.

Integration

The frontend communicates with the backend's /api/v1 endpoints:

Streaming: Consumes Server-Sent Events (SSE) for real-time agent reasoning and response delivery.
Visualization: Renders Matplotlib plots either from base64 strings in the event stream or binary retrieval from /artifacts/plots.

Development

npm install: Install dependencies.
npm run dev: Start development server.
npm run build: Build for production.
npm run test: Run Vitest unit tests.

Documentation

README: Main project documentation and setup guide.
Backend Guide: Backend implementation details.

2.7 KiB Raw Blame History