# jordantoulain/broussaudai architecture

> Architecture diagram of the GitHub repository jordantoulain/broussaudai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jordantoulain/broussaudai
- Repository: https://github.com/jordantoulain/broussaudai

## Overview

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 `Dockerfile`s 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.

Main entry points: [`web/src/app`](https://github.com/jordantoulain/broussaudai/tree/master/web/src/app) (Next.js app), [`web/src/services/api.js`](https://github.com/jordantoulain/broussaudai/blob/master/web/src/services/api.js) (API client), [`api/app/core/supabase_client.py`](https://github.com/jordantoulain/broussaudai/blob/master/api/app/core/supabase_client.py) (Supabase data), [`api/app/api/router.py`](https://github.com/jordantoulain/broussaudai/blob/master/api/app/api/router.py) (API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_web_app["Next.js app<br/>frontend shell"]
  node_web_auth["Auth flows<br/>frontend routes"]
  node_web_chat["Chat UI<br/>frontend routes"]
  node_web_admin["Admin UI<br/>frontend routes"]
  node_web_api["API client<br/>service layer<br/>[api.js]"]
  node_web_hooks["Client hooks<br/>state orchestration"]
  node_web_components["UI components<br/>component library"]
end

subgraph group_api["Backend API"]
  node_api_entry["FastAPI app<br/>api entrypoint<br/>[main.py]"]
  node_api_router["API router<br/>routing core<br/>[router.py]"]
  node_api_auth["Identity<br/>domain routes<br/>[auth.py]"]
  node_api_conversations["Conversations<br/>domain routes<br/>[conversations.py]"]
  node_api_admin["Admin domains<br/>domain routes<br/>[admin.py]"]
  node_api_ai["AI pipeline<br/>services"]
  node_api_storage[("Supabase data<br/>persistence boundary<br/>[supabase_client.py]")]
end

subgraph group_mcp["MCP service"]
  node_mcp_server["MCP server<br/>tool service<br/>[server.py]"]
  node_mcp_stats["Stats tools<br/>mcp tools<br/>[stats.py]"]
end

subgraph group_infra["Runtime"]
  node_runtime_stack["Docker stack<br/>deployment<br/>[docker-compose.yml]"]
  node_external_supabase[("Supabase<br/>external platform")]
  node_external_llm(("LLM provider<br/>external model"))
end

node_web_app -->|"routes to"| node_web_auth
node_web_app -->|"routes to"| node_web_chat
node_web_app -->|"routes to"| node_web_admin
node_web_app -->|"renders with"| node_web_components
node_web_app -->|"uses"| node_web_hooks
node_web_app -->|"calls"| node_web_api
node_web_auth -->|"auth calls"| node_web_api
node_web_chat -->|"chat calls"| node_web_api
node_web_admin -->|"admin calls"| node_web_api
node_web_api -->|"requests"| node_api_entry
node_api_entry -->|"mounts"| node_api_router
node_api_router -->|"includes"| node_api_auth
node_api_router -->|"includes"| node_api_conversations
node_api_router -->|"includes"| node_api_admin
node_api_auth -->|"reads/writes"| node_api_storage
node_api_conversations -->|"persists"| node_api_storage
node_api_admin -->|"manages"| node_api_storage
node_api_admin -->|"uses"| node_api_ai
node_api_ai -->|"generates via"| node_external_llm
node_api_ai -->|"retrieves"| node_api_storage
node_mcp_server -->|"exposes"| node_mcp_stats
node_mcp_server -->|"reads from"| node_external_supabase
node_runtime_stack -->|"runs"| node_api_entry
node_runtime_stack -->|"runs"| node_mcp_server
node_runtime_stack -->|"runs"| node_web_app
node_api_storage -->|"connects to"| node_external_supabase

click node_web_app "https://github.com/jordantoulain/broussaudai/tree/master/web/src/app"
click node_web_auth "https://github.com/jordantoulain/broussaudai/tree/master/web/src/app/login"
click node_web_chat "https://github.com/jordantoulain/broussaudai/tree/master/web/src/app/chat"
click node_web_admin "https://github.com/jordantoulain/broussaudai/tree/master/web/src/app/admin"
click node_web_api "https://github.com/jordantoulain/broussaudai/blob/master/web/src/services/api.js"
click node_web_hooks "https://github.com/jordantoulain/broussaudai/tree/master/web/src/hooks"
click node_web_components "https://github.com/jordantoulain/broussaudai/tree/master/web/src/components"
click node_api_entry "https://github.com/jordantoulain/broussaudai/blob/master/api/app/main.py"
click node_api_router "https://github.com/jordantoulain/broussaudai/blob/master/api/app/api/router.py"
click node_api_auth "https://github.com/jordantoulain/broussaudai/blob/master/api/app/api/routes/auth.py"
click node_api_conversations "https://github.com/jordantoulain/broussaudai/blob/master/api/app/api/routes/conversations.py"
click node_api_admin "https://github.com/jordantoulain/broussaudai/blob/master/api/app/api/routes/admin.py"
click node_api_ai "https://github.com/jordantoulain/broussaudai/blob/master/api/app/services/agent_orchestrator.py"
click node_api_storage "https://github.com/jordantoulain/broussaudai/blob/master/api/app/core/supabase_client.py"
click node_mcp_server "https://github.com/jordantoulain/broussaudai/blob/master/mcp/app/server.py"
click node_mcp_stats "https://github.com/jordantoulain/broussaudai/blob/master/mcp/app/tools/stats.py"
click node_runtime_stack "https://github.com/jordantoulain/broussaudai/blob/master/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_app,node_web_auth,node_web_chat,node_web_admin,node_web_api,node_web_hooks,node_web_components toneBlue
class node_api_entry,node_api_router,node_api_auth,node_api_conversations,node_api_admin,node_api_ai,node_api_storage toneAmber
class node_mcp_server,node_mcp_stats toneMint
class node_runtime_stack,node_external_supabase,node_external_llm toneRose
```

## Components

### Web app

Next.js frontend and client-side orchestration

- [Next.js app](https://github.com/jordantoulain/broussaudai/tree/master/web/src/app): frontend shell · App Router entrypoints, route groups, and page-level presentation · `web/src/app`
- [Auth flows](https://github.com/jordantoulain/broussaudai/tree/master/web/src/app/login): frontend routes · Login, register, MFA, logout, and auth actions · `web/src/app/login`
- [Chat UI](https://github.com/jordantoulain/broussaudai/tree/master/web/src/app/chat): frontend routes · Chat pages, archives, sidebar, and conversation presentation · `web/src/app/chat`
- [Admin UI](https://github.com/jordantoulain/broussaudai/tree/master/web/src/app/admin): frontend routes · Dashboard, documents, members, models, reviews, and system prompt screens · `web/src/app/admin`
- [API client](https://github.com/jordantoulain/broussaudai/blob/master/web/src/services/api.js): service layer · Central backend call layer used by the frontend · `web/src/services/api.js`
- [Client hooks](https://github.com/jordantoulain/broussaudai/tree/master/web/src/hooks): state orchestration · Chat, conversation, and user state management on the client · `web/src/hooks`
- [UI components](https://github.com/jordantoulain/broussaudai/tree/master/web/src/components): component library · Reusable auth, chat, admin, shared, and layout components · `web/src/components`

### Backend API

FastAPI application, domain routes, and AI services

- [FastAPI app](https://github.com/jordantoulain/broussaudai/blob/master/api/app/main.py): api entrypoint · Application startup and router assembly · `api/app/main.py`
- [API router](https://github.com/jordantoulain/broussaudai/blob/master/api/app/api/router.py): routing core · Top-level domain router composition · `api/app/api/router.py`
- [Identity](https://github.com/jordantoulain/broussaudai/blob/master/api/app/api/routes/auth.py): domain routes · Auth, MFA, sessions, and crypto-backed token handling · `api/app/api/routes/auth.py`
- [Conversations](https://github.com/jordantoulain/broussaudai/blob/master/api/app/api/routes/conversations.py): domain routes · Conversation and chat history endpoints · `api/app/api/routes/conversations.py`
- [Admin domains](https://github.com/jordantoulain/broussaudai/blob/master/api/app/api/routes/admin.py): domain routes · Admin, reviews, config, and data/document operations · `api/app/api/routes/admin.py`
- [AI pipeline](https://github.com/jordantoulain/broussaudai/blob/master/api/app/services/agent_orchestrator.py): services · LLM, agent orchestration, prompt handling, sanitization, and RAG · `api/app/services/agent_orchestrator.py`
- [Supabase data](https://github.com/jordantoulain/broussaudai/blob/master/api/app/core/supabase_client.py): persistence boundary · Database connectivity, schema bootstrap, and vector-backed retrieval storage · `api/app/core/supabase_client.py`

### MCP service

Auxiliary tool server sharing backend data

- [MCP server](https://github.com/jordantoulain/broussaudai/blob/master/mcp/app/server.py): tool service · Separate service boundary for external tool access · `mcp/app/server.py`
- [Stats tools](https://github.com/jordantoulain/broussaudai/blob/master/mcp/app/tools/stats.py): mcp tools · Operational/statistical read tools exposed by the MCP service · `mcp/app/tools/stats.py`

### Runtime

Containerized local deployment and shared external services

- [Docker stack](https://github.com/jordantoulain/broussaudai/blob/master/docker-compose.yml): deployment · Containerized local orchestration via Dockerfiles and compose · `docker-compose.yml`
- **Supabase**: external platform · Auth, PostgreSQL persistence, and vector search backend
- **LLM provider**: external model · Server-side generation provider used by the backend

## Connections

- Next.js app → Auth flows: routes to · Browser-facing auth pages and MFA flow
- Next.js app → Chat UI: routes to · Primary chat experience and archives
- Next.js app → Admin UI: routes to · Role-gated admin experience
- Next.js app → UI components: renders with · Shared UI building blocks
- Next.js app → Client hooks: uses · Client state orchestration
- Next.js app → API client: calls · Frontend API access layer
- Auth flows → API client: auth calls · Login, MFA, register, logout, session state
- Chat UI → API client: chat calls · Conversation and message operations
- Admin UI → API client: admin calls · Documents, members, reviews, models, config
- API client → FastAPI app: requests · Frontend targets the backend service
- FastAPI app → API router: mounts · Central route assembly
- API router → Identity: includes · Identity and session routes
- API router → Conversations: includes · Chat history and conversation routes
- API router → Admin domains: includes · Admin, reviews, config, and data routes
- Identity → Supabase data: reads/writes · Users, tokens, sessions, and auth state
- Conversations → Supabase data: persists · Conversation and message records
- Admin domains → Supabase data: manages · Documents, reviews, and operational data
- Admin domains → AI pipeline: uses · Prompting and generation for chat/admin features
- AI pipeline → LLM provider: generates via · Server-side LLM responses
- AI pipeline → Supabase data: retrieves · RAG and vector-backed knowledge lookup
- MCP server → Stats tools: exposes · Tool surface for external clients
- MCP server → Supabase: reads from · Shared data source via its own client
- Docker stack → FastAPI app: runs · Backend container
- Docker stack → MCP server: runs · MCP container
- Docker stack → Next.js app: runs · Next.js container
- Supabase data → Supabase: connects to · PostgreSQL and vector search boundary