ea-chatbot-lg/frontend/GEMINI.md

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.
  • 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).
• 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.