From af731413afbc54bf76c19a16592d0ba2800961ad Mon Sep 17 00:00:00 2001 From: Yunxiao Xu Date: Thu, 12 Feb 2026 01:49:37 -0800 Subject: [PATCH] docs(frontend): Update frontend/GEMINI.md with comprehensive architecture and authentication details --- frontend/GEMINI.md | 38 ++++++++++++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/frontend/GEMINI.md b/frontend/GEMINI.md index f044f62..fd9d421 100644 --- a/frontend/GEMINI.md +++ b/frontend/GEMINI.md @@ -1,18 +1,44 @@ # Election Analytics Chatbot - Frontend Guide ## Overview -This document serves as a guide for the frontend implementation of the Election Analytics Chatbot. +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**: UI library. -- **TypeScript**: Static typing. -- **Vite**: Build tool and dev server. Use v8. -- **Tailwind CSS**: Styling (if used, need to verify). Use v4. +- **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 API to stream agent responses and display analysis results, including charts and dataframes. +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.