jordantoulain/broussaudai

1. Repository shape

- This is a three-tier monorepo: a Next.js frontend in web/, a FastAPI backend in api/, and a small MCP server in mcp/.

- Supporting material lives in docs/ and deployment is containerized with Dockerfiles plus docker-compose.yml.

2. Primary request flow

- The browser talks to the Next.js app.

- The frontend calls the FastAPI API for authentication, chat, admin, documents, reviews, sessions, and configuration.

- The backend persists state in Supabase/PostgreSQL and also uses Supabase for vector search / document retrieval.

- AI responses are produced server-side through the backend’s LLM/RAG layer, not in the browser.

3. Frontend subsystem (web/)

- The frontend uses the Next.js App Router structure under src/app/, with separate route groups for login, register, chat, admin, maintenance, and logout.

- src/components/ is split by domain: auth, chat, admin, shared, layout, and ui.

- src/hooks/ contains the client-side state orchestration for chat, conversations, and user info.

- src/services/api.js centralizes backend calls, while src/app/actions/auth.js suggests some auth flow is handled via Next.js actions.

- The frontend is responsible for layout, forms, dialogs, charts, and session-aware presentation; it does not appear to own business logic.

4. Authentication and session boundary

- Authentication is split between frontend pages and backend endpoints under api/app/api/routes/auth.py, mfa.py, and sessions.py.

- The backend includes crypto_utils.py and supabase_client.py, indicating token handling and secure integration with Supabase-backed identity/data.

- The UI includes dedicated MFA screens in web/src/app/login/mfa/, so the auth flow includes a second factor step.

- Role-based access is implied by admin-specific frontend routes and backend routes like admin.py.

5. Backend API structure (api/)

- api/app/main.py is the FastAPI entry point, with routing assembled in api/app/api/router.py.

- Endpoints are organized by domain in api/app/api/routes/: auth, admin, chat/conversations, data, reviews, sessions, config, ia, and mfa.

- This suggests a clean boundary between API concerns: identity, conversation management, document/data operations, review workflows, and AI generation.

- The backend is the system of record for application state and business rules.

6. Chat, AI, and agent orchestration

- The AI subsystem lives mainly in api/app/services/.

- llm.py, agent.py, and agent_orchestrator.py indicate a layered design where an LLM wrapper feeds one or more agents, and an orchestrator coordinates them.

- rag_service.py is the retrieval layer: it likely fetches relevant document chunks from Supabase vector storage and injects them into prompts.

- Prompt templates are externalized in services/prompts/ (system_prompt.txt, qa_prompt.txt), which keeps model behavior separate from code.

- sanitize.py and utils.py suggest the AI pipeline includes input/output cleanup before responses are returned to the frontend.

7. Document and knowledge ingestion

- The backend exposes document/data functionality through api/app/api/routes/data.py.

- pdf_generator.py and font assets under api/app/services/fonts/ indicate server-side document rendering/export is part of the system.

- The README and file structure imply uploaded documents are normalized, chunked, embedded, and stored for retrieval.

- Supabase is the persistence and vector-search boundary for the knowledge base, so document ingestion directly feeds the RAG pipeline.

8. Administrative subsystem

- Admin functionality is split across backend routes and a dedicated frontend area under web/src/app/admin/.

- Frontend admin pages cover dashboard, documents, members, models, reviews, system prompt, and conversation inspection.

- Components like AdminSidebar, DocumentUploadForm, RoleDropdown, UserForm, and MiniChart show that the admin UI combines CRUD, moderation, and analytics.

- Backend admin.py and reviews.py likely enforce the privileged operations behind those screens.

9. Conversation and review model

- The application is not just a stateless chatbot; it tracks conversations, sessions, and reviews.

- Backend routes conversations.py, sessions.py, and reviews.py map to frontend chat archive pages and review modals.

- This indicates a workflow where user exchanges are stored, revisited, and possibly rated or moderated.

- The chat UI has a sidebar, archives, message lists, and review controls, so conversation history is a first-class domain object.

10. Data and persistence layer

- api/app/core/database.py and supabase_client.py indicate the backend owns database connectivity and Supabase integration.

- supabase_init.py is a bootstrap script for creating or initializing the schema; the README mentions users, conversations, messages, sessions, and related tables.

- core/supabase_init.py plus the RAG service imply the same backend database supports both transactional data and semantic retrieval.

- The MCP server has its own supabase_client.py, so it reads from the same backend data source but remains separated from the main API.

11. MCP subsystem (mcp/)

- mcp/app/server.py is a separate service boundary, distinct from the FastAPI API.

- mcp/app/tools/stats.py shows it exposes tools focused on operational statistics, likely for external context-aware clients.

- This is a lightweight auxiliary service rather than a core user-facing application path.

- Architecturally, it looks like a read-oriented integration layer over the same business data.

12. Deployment and runtime

- Each service has its own Docker image definition, and docker-compose.yml orchestrates local multi-service startup.

- The stack is split across Node.js/Next.js for the web app and Python/FastAPI for backend and MCP services.

- External dependencies that materially affect the architecture are Supabase for auth/data/vector storage and a Google GenAI / Gemini-style LLM for chat generation, as reflected in the README and service structure.

- docs/architecture.md and related docs likely describe the intended deployment and domain model in more detail, but the code layout already shows the main service boundaries clearly.