# youssefx64/nutriai architecture

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

- Interactive diagram: https://gitdiagram.com/youssefx64/nutriai
- Repository: https://github.com/youssefx64/nutriai

## Overview

1. **Overall shape**
   NutriAI is a two-tier full-stack application: a **FastAPI backend** that owns auth, document processing, RAG orchestration, and persistence; and a **React/Vite frontend** that provides the user-facing SaaS UI. In production, FastAPI serves the compiled frontend as static assets, so the system runs as a single externally exposed service.

2. **Frontend boundary**
   The frontend is a classic SPA with route-level pages for landing, auth, dashboard, documents, chat, and profile. `AuthContext` holds JWT state, while `services/api.js` is the HTTP boundary to the backend. The UI is organized around the core workflow: upload documents, process them, index them, then chat against the indexed knowledge base.

3. **Backend entry and API surface**
   `src/main.py` is the backend entrypoint. It wires FastAPI, CORS, API versioning, router registration, metrics, and static file serving. The API is split into focused route modules: `auth`, `data`, and `nlp`, plus schema modules for request/response validation.

4. **Auth and user/session boundary**
   Authentication is JWT-based and handled through the `auth` routes and database-backed user schema. The frontend stores the token and sends it as a Bearer credential to protected endpoints. This forms the main security boundary for all document and RAG operations.

5. **Project and tenant isolation**
   The repository models a **per-user, per-project** knowledge base. `ProjectModel` and related DB schemas provide the isolation layer so documents, chunks, and vector indexes are scoped to a project rather than being globally shared. That isolation is the key architectural boundary for multi-tenant behavior.

6. **Document ingestion pipeline**
   The `data` routes and `DataController` handle upload and file management for PDFs/TXT. Uploaded files are validated, stored, and then passed into the processing pipeline. `ProcessController` is the chunking stage: it converts source files into smaller `DataChunk` records with configurable chunk and overlap sizes.

7. **RAG orchestration layer**
   `NLPController` is the central orchestration point for retrieval-augmented generation. It coordinates embedding, vector search, prompt assembly, and answer generation. The readme’s sequence is reflected in the code structure: user question → embedding → retrieval of relevant chunks → grounded prompt → LLM response.

8. **Vector database abstraction**
   The repository abstracts vector storage behind `src/stores/vectordb`. Two backends are supported: **pgvector** in PostgreSQL and **Qdrant**. A factory selects the provider from environment configuration, so the retrieval layer is decoupled from the persistence choice.

9. **LLM and embedding abstraction**
   The LLM layer is similarly abstracted under `src/stores/llm`, with provider implementations for **Cohere** and **OpenAI**. The app can use one provider for embeddings and another for generation, controlled by env vars. This keeps the RAG pipeline provider-agnostic while still allowing model-specific behavior.

10. **Persistence and schema management**
   The main relational store is PostgreSQL, accessed via SQLAlchemy async models under `src/models/db_schemas/nutrition_rag`. The repo includes Alembic configuration and migration scaffolding, indicating that schema evolution is part of the deployment story. Core entities include users, projects, assets, and data chunks.

11. **Operational and deployment layer**
   `start.sh` and `dev.sh` define the two primary run modes: a production single-port startup and a development split frontend/backend setup. The `docker/` directory contains Compose, nginx, Prometheus, and app container definitions, showing that the repository is intended to be deployable as a containerized stack with observability.

12. **Observability and API usability**
   The backend exposes Prometheus metrics via `starlette-exporter`, and FastAPI’s Swagger/ReDoc docs are part of the public API surface. This means the operational boundary includes both runtime monitoring and self-documenting endpoints, which is useful for integration and debugging.

13. **Primary end-to-end data flow**
   The main business flow is: user authenticates → creates or selects a project → uploads a document → backend stores and chunks it → chunks are embedded and pushed to the vector DB → user asks a question → backend retrieves top-k relevant chunks → LLM generates an answer grounded in those chunks. That flow is the core architecture to capture in a diagram.

Main entry points: [`src/main.py`](https://github.com/youssefx64/nutriai/blob/main/src/main.py) (FastAPI App), [`docker/docker-compose.yml`](https://github.com/youssefx64/nutriai/blob/main/docker/docker-compose.yml) (Docker Stack), [`src/routes/data.py`](https://github.com/youssefx64/nutriai/blob/main/src/routes/data.py) (Data Routes), [`src/controllers/NLPController.py`](https://github.com/youssefx64/nutriai/blob/main/src/controllers/NLPController.py) (NLP Ctrl)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA<br/>React/Vite app<br/>[App.jsx]"]
  node_frontend_pages["Pages<br/>Route views"]
  node_frontend_auth(("Auth State<br/>React context<br/>[AuthContext.jsx]"))
  node_frontend_api["API Client<br/>HTTP boundary<br/>[api.js]"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI App<br/>API entrypoint<br/>[main.py]"]
  node_backend_auth["Auth Routes<br/>JWT auth API<br/>[auth.py]"]
  node_backend_data["Data Routes<br/>document API<br/>[data.py]"]
  node_backend_nlp["NLP Routes<br/>RAG API<br/>[nlp.py]"]
  node_backend_project["Project Ctrl<br/>tenant boundary"]
  node_backend_process["Process Ctrl<br/>chunking pipeline"]
  node_backend_nlp_ctrl["NLP Ctrl<br/>RAG orchestration<br/>[NLPController.py]"]
end

subgraph group_storage["Storage"]
  node_backend_models[("DB Models<br/>SQLAlchemy schemas")]
  node_storage_relational[("PostgreSQL<br/>relational store")]
  node_storage_vector_factory["Vector Factory<br/>provider selector"]
  node_storage_pgvector[("PGVector<br/>vector backend")]
  node_storage_qdrant[("Qdrant<br/>vector backend")]
  node_storage_llm_factory["LLM Factory<br/>model selector"]
  node_storage_openai["OpenAI<br/>LLM provider<br/>[OpenAIProvider.py]"]
  node_storage_cohere["Cohere<br/>LLM provider<br/>[CoHereProvider.py]"]
end

subgraph group_ops["Ops"]
  node_ops_runtime["Run Modes<br/>startup scripts<br/>[start.sh]"]
  node_ops_stack["Docker Stack<br/>container stack<br/>[docker-compose.yml]"]
  node_ops_metrics(("Metrics<br/>observability<br/>[metrics.py]"))
end

node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_auth -->|"auths"| node_frontend_api
node_frontend_app -->|"navigates"| node_frontend_pages
node_backend_main -->|"registers"| node_backend_auth
node_backend_main -->|"registers"| node_backend_data
node_backend_main -->|"registers"| node_backend_nlp
node_backend_main -->|"exposes"| node_ops_metrics
node_backend_auth -->|"uses"| node_backend_models
node_backend_data -->|"scopes"| node_backend_project
node_backend_data -->|"dispatches"| node_backend_process
node_backend_process -->|"stores"| node_backend_models
node_backend_nlp -->|"delegates"| node_backend_nlp_ctrl
node_backend_nlp_ctrl -->|"queries"| node_storage_vector_factory
node_backend_nlp_ctrl -->|"generates"| node_storage_llm_factory
node_storage_vector_factory -->|"selects"| node_storage_pgvector
node_storage_vector_factory -->|"selects"| node_storage_qdrant
node_storage_llm_factory -->|"selects"| node_storage_openai
node_storage_llm_factory -->|"selects"| node_storage_cohere
node_backend_models -->|"persists"| node_storage_relational
node_ops_runtime -->|"starts"| node_backend_main
node_ops_stack -->|"deploys"| node_backend_main
node_ops_stack -->|"provisions"| node_storage_relational
node_ops_stack -->|"supports"| node_storage_pgvector
node_ops_stack -->|"supports"| node_storage_qdrant

click node_frontend_app "https://github.com/youssefx64/nutriai/blob/main/frontend/src/App.jsx"
click node_frontend_pages "https://github.com/youssefx64/nutriai/tree/main/frontend/src/pages"
click node_frontend_auth "https://github.com/youssefx64/nutriai/blob/main/frontend/src/context/AuthContext.jsx"
click node_frontend_api "https://github.com/youssefx64/nutriai/blob/main/frontend/src/services/api.js"
click node_backend_main "https://github.com/youssefx64/nutriai/blob/main/src/main.py"
click node_backend_auth "https://github.com/youssefx64/nutriai/blob/main/src/routes/auth.py"
click node_backend_data "https://github.com/youssefx64/nutriai/blob/main/src/routes/data.py"
click node_backend_nlp "https://github.com/youssefx64/nutriai/blob/main/src/routes/nlp.py"
click node_backend_project "https://github.com/youssefx64/nutriai/blob/main/src/controllers/ProjectController.py"
click node_backend_process "https://github.com/youssefx64/nutriai/blob/main/src/controllers/ProcessController.py"
click node_backend_nlp_ctrl "https://github.com/youssefx64/nutriai/blob/main/src/controllers/NLPController.py"
click node_backend_models "https://github.com/youssefx64/nutriai/tree/main/src/models/db_schemas/nutrition_rag/schemas"
click node_storage_relational "https://github.com/youssefx64/nutriai/tree/main/src/models/db_schemas/nutrition_rag"
click node_storage_vector_factory "https://github.com/youssefx64/nutriai/blob/main/src/stores/vectordb/VectorDBProviderFactory.py"
click node_storage_pgvector "https://github.com/youssefx64/nutriai/blob/main/src/stores/vectordb/providers/PGVectorProvider.py"
click node_storage_qdrant "https://github.com/youssefx64/nutriai/blob/main/src/stores/vectordb/providers/QdrantDBProvider.py"
click node_storage_llm_factory "https://github.com/youssefx64/nutriai/blob/main/src/stores/llm/LLMProviderFactory.py"
click node_storage_openai "https://github.com/youssefx64/nutriai/blob/main/src/stores/llm/providers/OpenAIProvider.py"
click node_storage_cohere "https://github.com/youssefx64/nutriai/blob/main/src/stores/llm/providers/CoHereProvider.py"
click node_ops_runtime "https://github.com/youssefx64/nutriai/blob/main/start.sh"
click node_ops_stack "https://github.com/youssefx64/nutriai/blob/main/docker/docker-compose.yml"
click node_ops_metrics "https://github.com/youssefx64/nutriai/blob/main/src/utils/metrics.py"

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_frontend_app,node_frontend_pages,node_frontend_auth,node_frontend_api toneBlue
class node_backend_main,node_backend_auth,node_backend_data,node_backend_nlp,node_backend_project,node_backend_process,node_backend_nlp_ctrl toneAmber
class node_backend_models,node_storage_relational,node_storage_vector_factory,node_storage_pgvector,node_storage_qdrant,node_storage_llm_factory,node_storage_openai,node_storage_cohere toneMint
class node_ops_runtime,node_ops_stack,node_ops_metrics toneRose
```

## Components

### Frontend

React/Vite single-page app and UI state

- [SPA](https://github.com/youssefx64/nutriai/blob/main/frontend/src/App.jsx): React/Vite app · Client-side application shell and route handling · `frontend/src/App.jsx`
- [Pages](https://github.com/youssefx64/nutriai/tree/main/frontend/src/pages): Route views · Landing, auth, dashboard, documents, chat, and profile screens · `frontend/src/pages`
- [Auth State](https://github.com/youssefx64/nutriai/blob/main/frontend/src/context/AuthContext.jsx): React context · JWT storage and authenticated session state · `frontend/src/context/AuthContext.jsx`
- [API Client](https://github.com/youssefx64/nutriai/blob/main/frontend/src/services/api.js): HTTP boundary · Frontend service layer for backend requests · `frontend/src/services/api.js`

### Backend

FastAPI API, controllers, and orchestration

- [FastAPI App](https://github.com/youssefx64/nutriai/blob/main/src/main.py): API entrypoint · Wires routes, CORS, metrics, versioning, and static serving · `src/main.py`
- [Auth Routes](https://github.com/youssefx64/nutriai/blob/main/src/routes/auth.py): JWT auth API · Login, register, and token-protected session endpoints · `src/routes/auth.py`
- [Data Routes](https://github.com/youssefx64/nutriai/blob/main/src/routes/data.py): document API · Upload, file management, and project-scoped data access · `src/routes/data.py`
- [NLP Routes](https://github.com/youssefx64/nutriai/blob/main/src/routes/nlp.py): RAG API · Question answering and retrieval-augmented generation endpoints · `src/routes/nlp.py`
- [Project Ctrl](https://github.com/youssefx64/nutriai/blob/main/src/controllers/ProjectController.py): tenant boundary · Per-user project isolation and project lifecycle logic · `src/controllers/ProjectController.py`
- [Process Ctrl](https://github.com/youssefx64/nutriai/blob/main/src/controllers/ProcessController.py): chunking pipeline · Transforms uploaded files into chunks for indexing · `src/controllers/ProcessController.py`
- [NLP Ctrl](https://github.com/youssefx64/nutriai/blob/main/src/controllers/NLPController.py): RAG orchestration · Coordinates embedding, retrieval, prompt assembly, and answer generation · `src/controllers/NLPController.py`

### Storage

Relational, vector, and asset persistence

- [DB Models](https://github.com/youssefx64/nutriai/tree/main/src/models/db_schemas/nutrition_rag/schemas): SQLAlchemy schemas · Users, projects, assets, and chunk persistence models · `src/models/db_schemas/nutrition_rag/schemas`
- [PostgreSQL](https://github.com/youssefx64/nutriai/tree/main/src/models/db_schemas/nutrition_rag): relational store · Primary database for users, projects, assets, and chunks · `src/models/db_schemas/nutrition_rag`
- [Vector Factory](https://github.com/youssefx64/nutriai/blob/main/src/stores/vectordb/VectorDBProviderFactory.py): provider selector · Chooses pgvector or Qdrant backend from configuration · `src/stores/vectordb/VectorDBProviderFactory.py`
- [PGVector](https://github.com/youssefx64/nutriai/blob/main/src/stores/vectordb/providers/PGVectorProvider.py): vector backend · Vector search backed by PostgreSQL/pgvector · `src/stores/vectordb/providers/PGVectorProvider.py`
- [Qdrant](https://github.com/youssefx64/nutriai/blob/main/src/stores/vectordb/providers/QdrantDBProvider.py): vector backend · External vector database provider · `src/stores/vectordb/providers/QdrantDBProvider.py`
- [LLM Factory](https://github.com/youssefx64/nutriai/blob/main/src/stores/llm/LLMProviderFactory.py): model selector · Chooses embedding and generation provider from configuration · `src/stores/llm/LLMProviderFactory.py`
- [OpenAI](https://github.com/youssefx64/nutriai/blob/main/src/stores/llm/providers/OpenAIProvider.py): LLM provider · Embedding and/or generation provider implementation · `src/stores/llm/providers/OpenAIProvider.py`
- [Cohere](https://github.com/youssefx64/nutriai/blob/main/src/stores/llm/providers/CoHereProvider.py): LLM provider · Embedding and/or generation provider implementation · `src/stores/llm/providers/CoHereProvider.py`

### Ops

Run scripts, containers, and observability

- [Run Modes](https://github.com/youssefx64/nutriai/blob/main/start.sh): startup scripts · Production and development entry scripts · `start.sh`
- [Docker Stack](https://github.com/youssefx64/nutriai/blob/main/docker/docker-compose.yml): container stack · Compose, nginx, app, and supporting containers · `docker/docker-compose.yml`
- [Metrics](https://github.com/youssefx64/nutriai/blob/main/src/utils/metrics.py): observability · Prometheus scraping and runtime metrics endpoint · `src/utils/metrics.py`

## Connections

- Pages → API Client: calls · UI actions invoke backend requests through the client boundary
- Auth State → API Client: auths · Bearer token state is attached to protected requests
- SPA → Pages: navigates · Application shell renders route-level pages
- FastAPI App → Auth Routes: registers · FastAPI mounts the authentication routes
- FastAPI App → Data Routes: registers · FastAPI mounts the data routes
- FastAPI App → NLP Routes: registers · FastAPI mounts the NLP routes
- FastAPI App → Metrics: exposes · Runtime metrics are published for scraping
- Auth Routes → DB Models: uses · Auth operations persist and read user records
- Data Routes → Project Ctrl: scopes · Data access is partitioned by project ownership
- Data Routes → Process Ctrl: dispatches · Uploaded documents are sent into the processing pipeline
- Process Ctrl → DB Models: stores · Chunking produces persisted chunk and asset records
- NLP Routes → NLP Ctrl: delegates · Request handling is orchestrated by the NLP controller
- NLP Ctrl → Vector Factory: queries · Retrieval uses the configured vector backend
- NLP Ctrl → LLM Factory: generates · Answer generation uses the configured model provider
- Vector Factory → PGVector: selects · One supported vector backend is pgvector
- Vector Factory → Qdrant: selects · One supported vector backend is Qdrant
- LLM Factory → OpenAI: selects · One supported provider is OpenAI
- LLM Factory → Cohere: selects · One supported provider is Cohere
- DB Models → PostgreSQL: persists · SQLAlchemy models map to PostgreSQL storage
- Run Modes → FastAPI App: starts · Scripts launch the backend service
- Docker Stack → FastAPI App: deploys · Container stack packages the application runtime
- Docker Stack → PostgreSQL: provisions · Deployment includes PostgreSQL
- Docker Stack → PGVector: supports · Deployment can use pgvector-backed retrieval
- Docker Stack → Qdrant: supports · Deployment can use Qdrant-backed retrieval
