How youssefx64/nutriai works
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: main.py FastAPI App · docker-compose.yml Docker Stack · data.py Data Routes · NLPController.py NLP Ctrl
Components 22
Frontend
React/Vite single-page app and UI state
- SPA · Client-side application shell and route handling
frontend/src/App.jsx - Pages · Landing, auth, dashboard, documents, chat, and profile screens
frontend/src/pages - Auth State · JWT storage and authenticated session state
frontend/src/context/AuthContext.jsx - API Client · Frontend service layer for backend requests
frontend/src/services/api.js
Backend
FastAPI API, controllers, and orchestration
- FastAPI App · Wires routes, CORS, metrics, versioning, and static serving
src/main.py - Auth Routes · Login, register, and token-protected session endpoints
src/routes/auth.py - Data Routes · Upload, file management, and project-scoped data access
src/routes/data.py - NLP Routes · Question answering and retrieval-augmented generation endpoints
src/routes/nlp.py - Project Ctrl · Per-user project isolation and project lifecycle logic
src/controllers/ProjectController.py - Process Ctrl · Transforms uploaded files into chunks for indexing
src/controllers/ProcessController.py - NLP Ctrl · Coordinates embedding, retrieval, prompt assembly, and answer generation
src/controllers/NLPController.py
Storage
Relational, vector, and asset persistence
- DB Models · Users, projects, assets, and chunk persistence models
src/models/db_schemas/nutrition_rag/schemas - PostgreSQL · Primary database for users, projects, assets, and chunks
src/models/db_schemas/nutrition_rag - Vector Factory · Chooses pgvector or Qdrant backend from configuration
src/stores/vectordb/VectorDBProviderFactory.py - PGVector · Vector search backed by PostgreSQL/pgvector
src/stores/vectordb/providers/PGVectorProvider.py - Qdrant · External vector database provider
src/stores/vectordb/providers/QdrantDBProvider.py - LLM Factory · Chooses embedding and generation provider from configuration
src/stores/llm/LLMProviderFactory.py - OpenAI · Embedding and/or generation provider implementation
src/stores/llm/providers/OpenAIProvider.py - Cohere · Embedding and/or generation provider implementation
src/stores/llm/providers/CoHereProvider.py
Ops
Run scripts, containers, and observability
- Run Modes · Production and development entry scripts
start.sh - Docker Stack · Compose, nginx, app, and supporting containers
docker/docker-compose.yml - Metrics · Prometheus scraping and runtime metrics endpoint
src/utils/metrics.py
Connections 24
- 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