# 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](../README.md)**: Main project documentation and setup guide.
- **[Backend Guide](../backend/GEMINI.md)**: Backend implementation details.