Overview · Features · Showcase · Architecture · RAG · Getting started · Deployment · API
FitAI is a conversational fitness coach for gym-goers, fitness enthusiasts and nutrition-conscious people. Generic chatbots forget who you are and answer from a model's memory alone. FitAI is built to do the opposite: it remembers your profile and history, grounds its answers in retrieved documents, computes numbers deterministically, and shows where an answer came from.
It combines five things in one application:
| Capability | What it means in FitAI |
|---|---|
| Conversational AI | A LangGraph agent, backed by the Groq API, handles every chat turn. |
| Retrieval-Augmented Generation | Answers can draw on a shared curated knowledge base and on the user's own uploaded documents, and carry source references. |
| Persistent personalization | A structured profile and a fact-level memory (current vs. historical) carry context across conversations. |
| Training and progress records | Planned and logged workouts, body measurements and derived progress metrics live in PostgreSQL, not in the model. |
| Deterministic tools | BMI, BMR, TDEE, calorie and macro targets, one-rep-max estimates and trend analysis are calculated by code. |
They work together on each turn: safety checks run first, then the agent decides whether the message is a personal statement (extract and store facts), a question (retrieve context) or both, and finally generates a reply from your memory, your records, retrieved passages and any tool results.
Disclaimer. FitAI provides general fitness and nutrition guidance. It is not a medical, diagnostic or treatment service, and its output can be wrong. Consult a qualified professional for medical advice.
| Feature | What it does | How it works |
|---|---|---|
| AI fitness coaching | Training, nutrition and recovery conversations with history and search. | LangGraph agent (backend/app/agent) calling Groq (backend/app/llm). Responses are returned as a complete JSON reply (no token streaming). |
| Workout planning and logging | Plan sessions on a calendar, log what you did, apply templates, mark planned sessions complete. | plan and workouts routers over PostgreSQL; exercise library with global and per-user custom exercises. |
| Progress tracking | Weight, height, body fat, waist, sleep and steps series; BMI; training volume, streaks and personal records. | progress router and tools over stored measurements and sessions. |
| Nutrition assistance | Calorie targets, macro splits and nutrition Q&A grounded in your knowledge base. | Deterministic calculators (calculations.py) plus RAG. Meal-by-meal food logging is not implemented. |
| RAG over documents | Upload PDF, DOCX, TXT or Markdown and ask questions about them. | Validate, chunk, embed and index per user; see RAG pipeline. |
| Source references | Retrieved passages carry a source name and page; web-research answers list numbered sources. | RetrievedChunk.citation() and the sources array of the chat response. |
| Persistent memory | Durable facts about you (goals, preferences, injuries, routines) that you can review, correct and delete. | Extraction, change detection and confirmation flow; see Memory. |
| Cross-chat continuity | Earlier conversations inform later ones. | Pinned core memory, semantic recall of memories and past-chat summaries, each with a per-user toggle. |
| Safety guardrails | Out-of-scope, unsafe and prompt-injection requests are stopped before any tool runs. | Deterministic rules plus an optional LLM intent classifier and an optional prompt-injection screen. |
| Optional web and location tools | Current information, weather, geocoding and nearby gyms. | Tool calls behind feature flags (AGENT_WEB_TOOLS, AGENT_LOCATION_TOOLS). |
| Authentication and data isolation | Each user only sees their own data. | Supabase Auth tokens verified server-side; every query scoped to the user; PostgreSQL Row Level Security as a second layer. |
| Voice dictation | Speak a message instead of typing. | Browser Web Speech API only; there is no speech backend (frontend/SPEECH_TO_TEXT.md). |
Screenshots from the running application (demo account).
The application also includes Library (document upload and status), Memory (review, correct and delete what FitAI remembers) and Profile / Settings pages.
Illustrative overview. The diagram shows a Vercel + Render split; the default Blueprint in this repository serves the frontend and API from one Render service (see Deployment). Chat replies are returned as a single JSON response rather than streamed.
flowchart LR
U([User]) --> FE["Frontend - React 19 and Vite SPA"]
FE -->|HTTPS and Bearer token| API["FastAPI /api/v1"]
FE -->|sign-in and refresh| SA["Supabase Auth"]
API --> AUTH{"Verify JWT"}
AUTH -->|invalid| E401["401 error"]
AUTH -->|valid| SAFE["Safety and guardrails"]
SAFE -->|blocked| REF["Safe refusal"]
SAFE -->|allowed| G["LangGraph agent"]
G --> PG[("PostgreSQL: profile, memory, history, records")]
G --> VS[("Vector store: pgvector in production")]
G --> LLM["Groq LLM"]
G --> T["Optional tools: web, weather, places"]
G --> RESP["Reply, sources and actions"]
REF --> RESP
RESP --> FE
Frontend
- React 19, TypeScript, Vite, React Router,
react-markdownwith GFM,@supabase/supabase-js,lucide-react. Tests use Vitest, Testing Library and jsdom; linting uses oxlint. - Pages: Landing, Login, Chat, Library, Memory, Plan, Progress, Profile/Settings (
frontend/src/pages). Secondary pages are lazy-loaded. - Authentication: Supabase Auth in the browser; the access token is sent as
Authorization: Bearer …to the backend, and a 401 response signs the user out (frontend/src/services,context). - API access goes through a single client against
VITE_API_BASE_URL(default/api/v1, proxied by Vite in development). The browser never talks to the database directly.
Backend
- FastAPI with a layered modular monolith: Router → Schema → Service → Repository → Model (
backend/app). Pydantic 2 validates every input; SQLAlchemy 2 and Alembic handle persistence and migrations. - Cross-cutting HTTP middleware: request IDs, a uniform JSON error envelope, security headers, CORS and rate limiting (
core/service_app.py,core/http_security.py). - Authentication dependency verifies Supabase JWTs against the project's JWKS (
core/security.py); the user identity comes only from verified claims. - The AI engine (agent, memory, RAG, tools, LLM, guardrails) reaches persistence through the same service layer as the rest of the backend.
- In production one process serves the API, the built frontend and an in-process, database-backed ingestion worker.
Data layer
- PostgreSQL (Supabase) is the source of truth for users, profiles, conversations, messages, memories and their history, documents and ingestion jobs, exercises, planned and logged workouts, measurements and activity events.
- Vector storage is selected by
VECTOR_STORE_BACKEND:pgvector(tablevector_chunks, PostgreSQL) in the production Blueprint, or embedded ChromaDB as the local-development default. - Document storage holds the original uploads: a private Supabase Storage bucket in production (
DOCUMENT_STORAGE_BACKEND=supabase), or the local filesystem in development. - Row Level Security is enabled on every application table by migration
ca4d2c439416. The API connects with a role that bypasses RLS, so ownership is additionally enforced in application code.
AI layer
- LLM: Groq, via the
groqSDK. The model is set byGROQ_MODEL(the template usesopenai/gpt-oss-120b). Separate, optional models can be set for routing, research, synthesis, summaries, structured extraction and the guard classifier. - Embeddings: configurable. Local development defaults to a local sentence-transformers model (
all-MiniLM-L6-v2, 384 dimensions). The production Blueprint uses a remote OpenAI-format embeddings endpoint (Qwen/Qwen3-Embedding-0.6Bthrough the Hugging Face router, 1024 dimensions) and requires its own API key. - Reranking: optional sentence-similarity reranking through Hugging Face (
HF_RERANKING_ENABLED). It is off by default and off in the Blueprint; when disabled or failing, retrieval keeps vector-similarity order. - Orchestration: LangGraph. A multi-agent router/research/synthesis path exists behind
AGENT_MULTI_AGENT.
flowchart TD
A["Upload: PDF, DOCX, TXT or MD"] --> B{"Validate size, extension and file signature"}
B -->|rejected| X["Error 413 or 415 - nothing stored"]
B -->|ok| C["Store original in Supabase Storage"]
C --> D["Create document row and ingestion job"]
D --> E["Worker extracts text in page batches"]
E --> F["Chunk: about 1000 chars, 150 overlap"]
F --> G["Embed with remote or local model"]
G --> H[("Vector store: rows scoped by owner_id")]
H --> I["Status ready or failed with a reason"]
Q["User question"] --> R["Retrieve top-k from curated and the user's own collection"]
H --> R
R --> S["Optional rerank"]
S --> T["Build prompt: memory, records, passages"]
T --> L["Groq LLM"]
L --> V["Answer with source references"]
- Upload.
POST /api/v1/documentsaccepts PDF, DOCX, TXT and Markdown up toMAX_UPLOAD_SIZE_MB(10 by default). Identical bytes uploaded twice by the same user return the existing item. - Validation. The extension is checked against the supported list and the content is verified against its claimed type (PDF/DOCX signatures; text files must not be binary) before anything is stored. Filenames are sanitised and storage keys are server-generated.
- Ingestion. In production a database-backed job queue drives a worker inside the API process. Jobs are checkpointed in page batches, survive restarts, are retried a bounded number of times and end as
readyorfailedwith a short, readable reason. - Chunking. Text is split on natural boundaries (paragraph, line, sentence, word) into roughly 1000-character chunks with 150 characters of overlap, keeping the page number for PDFs.
- Embedding and storage. Chunks are embedded in batches and written to the vector store with an
owner_id, document ID and embedding-model metadata. A dimension mismatch is rejected before it reaches the index. - User-scoped retrieval. For a question the retriever queries the shared
fitness_knowledgecollection (curated, visible to everyone) and theuser_documentscollection filtered to the asking user. Results below a minimum similarity (0.2) are dropped and duplicates removed; the top k (4 by default) are kept. - Context construction. Retrieved passages are added to the prompt alongside pinned memory, recalled continuity and your stored fitness context.
- Generation. Groq produces the reply from that context.
- References. Retrieved chunks carry
sourceandpage; research-style answers return numberedsources(title, URL, snippet) in the chat response.
Curated knowledge is ingested by an operator with python -m scripts.ingest_knowledge from files in knowledge_base/. This repository does not ship source documents.
FitAI separates structured data in PostgreSQL from vector-based recall:
| Layer | Stored in | Used for |
|---|---|---|
| Profile | user_profiles (PostgreSQL) |
Height, weight, goal, activity level, location, units. Editable on the Profile page. |
| Memory facts | memories, memory_history (PostgreSQL) |
Durable facts with a key, value, timestamps and a current/historical distinction. |
| Pending proposals | pending_memory_updates |
Ambiguous or conflicting changes wait for explicit confirmation. |
| Records | workouts, sets, planned sessions, measurements | Exact numbers answered from data, never guessed. |
| Semantic recall | vector store (user_continuity) |
Finds relevant memories and past-chat summaries by meaning. |
| Past-chat summaries | conversation_summaries |
Short summaries of earlier conversations. |
flowchart LR
M["User message"] --> G{"Safety gate"}
G --> P{"Personal statement?"}
P -->|yes| X["Extract candidate facts"]
X --> D["Compare with current memory"]
D --> A{"Explicit and high confidence?"}
A -->|yes| W["Write memory and history"]
A -->|no| Q["Propose to the user: confirm or reject"]
P -->|no| R["Retrieve memory, records, documents"]
W --> R
R --> L["Generate reply"]
- A statement like "I used to weigh 90 kg" is recorded as history and does not overwrite the current value; hypotheticals are ignored.
- Structured extraction uses a dedicated, optional Groq key and model (
GROQ_EXTRACTION_*). Without that key, extraction is disabled and chat works normally. - Users can toggle memory recall and past-chat recall, and can edit or delete any memory from the Memory page. Deleted facts do not come back.
- Details:
docs/extraction.md.
| Area | Technologies |
|---|---|
| Frontend | React 19, TypeScript, Vite, React Router, react-markdown + remark-gfm, lucide-react |
| Backend | Python 3.10+, FastAPI, Uvicorn, Pydantic 2, SQLAlchemy 2, Alembic, structlog |
| Database | PostgreSQL (Supabase); SQLite is used only by the test suite |
| AI / LLM | Groq API (default model family openai/gpt-oss), LangGraph, LangChain Core |
| RAG and embeddings | pgvector (production) / ChromaDB (local default); remote embeddings (Qwen3-Embedding-0.6B via the Hugging Face router) or local sentence-transformers; optional Hugging Face reranking; pypdf, python-docx, RapidOCR for images |
| Authentication | Supabase Auth; JWT verification with PyJWT and JWKS |
| Storage | Supabase Storage (private bucket) or local filesystem |
| Deployment | Docker (multi-stage), Render, Vercel (optional split deployment) |
| Development and testing | Pytest, Ruff, MyPy, Vitest, Testing Library, oxlint, GitHub Actions |
FitAI/
├── frontend/ React + TypeScript + Vite app
│ ├── src/pages/ Chat, Library, Memory, Plan, Progress, Profile, Login, Landing
│ ├── src/components/ chat, layout, plan, progress and shared UI
│ ├── src/services/ API client, Supabase client, speech helpers
│ ├── src/context/ auth context
│ └── vercel.json headers and SPA rewrites for Vercel
├── backend/
│ ├── app/
│ │ ├── main.py application entry point
│ │ ├── api/ dependencies and routers (/api/v1)
│ │ ├── schemas/ Pydantic request/response models
│ │ ├── services/ business logic (documents, ingestion jobs, workouts…)
│ │ ├── repositories/ database access
│ │ ├── models/ SQLAlchemy entities
│ │ ├── agent/ LangGraph state, nodes and routing (+ multi-agent path)
│ │ ├── memory/ change detection, confirmation, continuity, summaries
│ │ ├── extraction/ structured fact extraction and reconciliation
│ │ ├── rag/ loader, chunker, embeddings, vector stores, retriever, reranker
│ │ ├── guardrails/ safety/ intent classifier, deterministic rules, prompt guard
│ │ ├── tools/ calculators, workout/progress tools, web and location tools
│ │ ├── llm/ Groq client and prompts
│ │ └── core/ config, auth, logging, errors, HTTP security
│ ├── migrations/ Alembic migrations (including RLS)
│ ├── tests/ api, unit, integration, guardrails, security
│ └── Dockerfile* backend images
├── Dockerfile.web single-service image: built frontend + API
├── render.yaml Render Blueprint (single web service)
├── render.split.yaml Render Blueprint for the two-service layout
├── docs/ setup, API conventions, deployment, models, extraction, security audit
├── knowledge_base/ drop-in folder for curated documents (see its README)
├── scripts/ dev runners, ingestion and smoke-test utilities
└── .github/workflows/ backend, frontend, secret-scan and dependency-audit CI
- Python 3.10+ and Node.js 22 (the version used by the Docker build) with npm
- A Supabase project (Auth is required; a PostgreSQL database and, optionally, a private Storage bucket)
- A Groq API key for chat
- PostgreSQL reachable through
DATABASE_URL(Supabase works; the local default expectslocalhost:5432)
git clone https://github.com/prnvvv/FitAI.git
cd FitAIWindows (PowerShell)
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env # then edit .env
alembic upgrade head
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000macOS / Linux
cd backend
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
cp .env.example .env # then edit .env
alembic upgrade head
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000At minimum set DATABASE_URL, SUPABASE_URL and GROQ_API_KEY in backend/.env. uv sync --extra dev (used by CI) is an equivalent way to install. The backend refuses to start if the database schema is behind the latest migration, so run alembic upgrade head first. See docs/setup.md for the full runbook.
cd frontend
npm install
cp .env.example .env.local # PowerShell: Copy-Item .env.example .env.local
npm run devSet VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY. Leave VITE_API_BASE_URL unset in development: Vite proxies /api/v1 to the backend.
| URL | What |
|---|---|
| http://127.0.0.1:5173 | Frontend (Vite dev server) |
| http://127.0.0.1:8000/docs | Interactive API docs (development only) |
| http://127.0.0.1:8000/health | Liveness probe |
| http://127.0.0.1:8000/health/ready | Readiness probe (checks the database) |
Run both together from the repository root: npm install then npm run dev (starts the backend on :8000 and the frontend). scripts/dev.ps1 and scripts/run-all.sh are alternative wrappers.
backend/.env.example and frontend/.env.example are the source of truth; each variable is commented there. Real .env files are git-ignored. Never commit secrets.
Backend variables (most important)
| Variable | Required | Secret? | Purpose / where to get it |
|---|---|---|---|
ENVIRONMENT |
yes | no | development or production. Production refuses to start with an unsafe configuration. |
DATABASE_URL |
yes | yes | PostgreSQL URL with the postgresql+psycopg2:// driver (Supabase → Database → connection string, pooled). |
SUPABASE_URL |
yes | no | Supabase project URL; drives JWKS and the expected token issuer. |
SUPABASE_JWT_ALGORITHMS |
no | no | Accepted signing algorithms (default ES256,RS256). |
SUPABASE_JWT_SECRET |
no | yes | Only for legacy HS256 projects; leave empty otherwise. |
SUPABASE_SERVICE_ROLE_KEY |
with Supabase Storage | yes | Server-side only. Never expose to the frontend. |
GROQ_API_KEY |
yes (chat) | yes | console.groq.com. |
GROQ_MODEL |
no | no | Chat model id. |
GROQ_EXTRACTION_API_KEY / GROQ_EXTRACTION_MODEL |
no | key: yes | Dedicated memory-extraction model. Blank key disables extraction. |
CORS_ORIGINS |
yes (prod) | no | Comma-separated explicit https:// origins. |
DOCUMENT_STORAGE_BACKEND |
for uploads | no | unconfigured, local or supabase. |
SUPABASE_STORAGE_BUCKET |
with supabase |
no | Private bucket name (fitai-documents). |
VECTOR_STORE_BACKEND |
no | no | chroma (local default) or pgvector. |
EMBEDDING_PROVIDER, EMBEDDING_API_URL, EMBEDDING_API_KEY, EMBEDDING_REMOTE_MODEL, EMBEDDING_DIMENSION |
with pgvector |
key: yes | Remote embeddings provider; the dimension must match the database column (1024 in production). |
HF_TOKEN, HF_RERANKING_ENABLED |
no | token: yes | Optional reranking (off by default). |
INGESTION_MODE |
no | no | inline (local) or jobs (durable queue used in production). |
GUARDRAILS_MODE, PROMPT_GUARD_API_KEY |
no | key: yes | Guardrail enforcement and optional prompt-injection screening. |
AGENT_WEB_TOOLS, AGENT_LOCATION_TOOLS, AGENT_MULTI_AGENT, SEARCH_PROVIDERS |
no | no | Feature flags and providers for optional tools (search provider keys are secret). |
RATE_LIMIT_*, TRUST_PROXY_HEADERS, EXPOSE_API_DOCS |
no | no | HTTP hardening; see Security. |
Frontend variables
| Variable | Required | Secret? | Purpose |
|---|---|---|---|
VITE_SUPABASE_URL |
yes | no (public) | Supabase project URL. |
VITE_SUPABASE_ANON_KEY |
yes | no (public by design) | Supabase anon / publishable key. Protected by Row Level Security. |
VITE_API_BASE_URL |
production split deploys | no | Backend URL including /api/v1. Defaults to /api/v1. |
VITE_DOCUMENTS_URL |
no | no | Only for a separate documents service. |
Everything prefixed VITE_ is embedded in the browser bundle. Never put a service-role key or any other secret in a VITE_ variable.
Dockerfile.web builds a single image containing the compiled frontend and the FastAPI backend. It runs as a non-root user, with one Uvicorn worker, and has a built-in health check. Run commands from the repository root.
# Build (the two VITE_ values are public and baked into the bundle)
docker build -f Dockerfile.web -t fitai-web:latest \
--build-arg VITE_SUPABASE_URL=https://<project>.supabase.co \
--build-arg VITE_SUPABASE_ANON_KEY=<anon-key> .
# Run (secrets come from an env file that is NOT committed)
docker run -d --name fitai-web -p 8000:8000 --env-file backend/.env fitai-web:latest
docker logs -f fitai-web # view logs
curl http://localhost:8000/health # health check
docker inspect --format '{{.State.Health.Status}}' fitai-web
docker stop fitai-web && docker rm fitai-web # stop and remove- The container listens on
$PORT(default8000); map it with-p <host>:8000. - The image sets
ENVIRONMENT=production, so the production safety checks apply: you need a PostgreSQLDATABASE_URL, anhttps://CORS_ORIGINSentry,SUPABASE_URL,GROQ_API_KEYand a valid storage and embeddings configuration. OverrideENVIRONMENTonly for throwaway local experiments. - The image does not run migrations at start-up; apply them once beforehand:
alembic upgrade headagainst the target database. backend/Dockerfile(withdocker-entrypoint.sh) is an older backend-only image that does run migrations on start.
Local Docker vs. production. Locally you pass an env file and reach the container on localhost. In production the platform injects environment variables, terminates TLS, calls /health, and the database, Storage and vector data live in Supabase rather than in the container (the container filesystem is scratch space only).
render.yaml deploys one Docker web service that serves the React app and the API from the same origin (no cross-origin CORS between them):
Browser ──► Render (Docker: FastAPI + built frontend + in-process ingestion worker)
├─► Supabase Postgres (+ pgvector), Auth, private Storage bucket
├─► Groq chat and extraction
└─► Remote embeddings provider (and optional Hugging Face reranking)
- Create a Supabase project (Auth, Postgres, a private
fitai-documentsbucket) and apply the migrations once:alembic upgrade head. - Apply the Blueprint and set the variables marked
sync: false(DATABASE_URL,CORS_ORIGINS,SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY,GROQ_API_KEY, embedding key, and the two publicVITE_build values). CORS_ORIGINSmust be the service's ownhttps://origin.- Health check path:
/health. Auto-deploy is off by default.
frontend/vercel.json (SPA rewrites, caching and security headers) supports hosting the static frontend on Vercel. Set VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY and VITE_API_BASE_URL (backend URL + /api/v1), and list the Vercel origin in the backend's CORS_ORIGINS. If the API is not on *.onrender.com, add its origin to connect-src in vercel.json. render.split.yaml describes the two-backend-service layout.
- Single instance. The image runs one worker; rate-limit counters and the ingestion worker are per-process. Do not scale horizontally without replacing the in-process limiter.
- No persistent disk is required: originals live in Supabase Storage, vectors and jobs in Postgres.
- Free-tier cold starts on Render add latency to the first request.
- Read
docs/deployment.mdbefore the first deploy.
All application routes live under /api/v1. Except for the health probes, every route requires Authorization: Bearer <Supabase access token>; an invalid or missing token returns 401 with the standard error envelope.
| Group | Prefix | Purpose |
|---|---|---|
| Auth | /auth |
GET /me — identity from the verified token |
| Chat | /chat |
POST a message, receive the reply |
| Conversations | /conversations |
CRUD and paginated /messages |
| Profile | /profile |
Read, replace (PUT) and update (PATCH) the profile |
| Memory | /memory |
Facts, history, pending proposals with confirm / reject |
| Documents | /documents |
Upload, list, rename, retry, delete |
| Plan | /plan |
Planned sessions, day summary, templates |
| Workouts | /workouts |
Logged sessions and sets |
| Progress | /progress |
Measurements, series, BMI, derived metrics, records |
| Exercises | /exercises |
Global and custom exercise library |
| Location | /location |
Geocode and reverse geocode |
| Activity | /activity |
Activity log |
Unprefixed: GET /health, GET /health/ready, GET /health/guardrails.
Example: send a chat message
POST /api/v1/chat
Authorization: Bearer <access-token>
Content-Type: application/json
{ "message": "Help me plan my week", "conversation_id": null }message is 1–4000 characters; conversation_id is optional (omit it to start a new conversation). The response contains conversation_id, response, title, sources[] (index, title, url, snippet), actions[] (for example a pending memory confirmation) and tool_events[].
List endpoints return { "items": [], "total": 0, "limit": 20, "offset": 0 } and accept limit (1–100) and offset.
Interactive docs are served at /docs in development and are disabled in production unless EXPOSE_API_DOCS=true. Contracts are summarized in docs/api.md.
- Ownership. Every user-owned row is scoped to the authenticated user in repository queries. Tables reached indirectly (messages, workout sets, planned exercises) are checked through their parent. Another user's resource returns
404. - Row Level Security. Enabled on all application tables, with owner policies and a deny policy for the anonymous role (
backend/migrations/versions). It is defence in depth; the application enforces ownership itself. - Authentication. Supabase Auth issues tokens; the backend verifies signature, issuer, audience and expiry with an algorithm allow-list. No passwords are handled by FitAI.
- Documents. Uploads are type- and content-validated, stored under server-generated keys in a private bucket, and retrieved only for their owner.
- Transport and browser hardening. HSTS, a Content-Security-Policy, framing and sniffing protection, and explicit CORS allow-lists.
- Abuse protection. Per-client rate limits on chat, uploads and other write paths; repeated failed authentication is throttled.
- Secrets. Provided only through environment variables; only the public Supabase anon key reaches the browser, and CI scans for committed credentials and for secrets in the built bundle.
Report vulnerabilities privately as described in SECURITY.md. The full audit, residual risks and required platform settings are in docs/SECURITY_AUDIT.md.
# Backend (from backend/)
python -m pytest -q # full suite; in-memory SQLite, no live credentials needed
ruff check . # lint
ruff format --check . # formatting
mypy app # type checking (configured in pyproject.toml)
# Frontend (from frontend/)
npm run lint # oxlint
npm run type-check # tsc -b
npm test # vitest
npm run build # production build
npm run check:bundle # scan dist/ for secrets and source mapsFrom the repository root: npm run test:backend, npm run test:frontend, npm run type-check:frontend, npm run build:frontend.
The backend suite mocks Groq and runs against an isolated in-memory database, so ordinary runs need no Supabase, Groq or Hugging Face credentials. A few tests that touch uploads expect DOCUMENT_STORAGE_BACKEND=local (CI sets it); PostgreSQL/pgvector integration tests are skipped unless a database is configured.
Continuous integration (GitHub Actions): backend lint + format + tests, frontend lint + type-check + tests + build + bundle scan, a committed-credential scan, and a weekly advisory dependency audit.
Current limitations
- Pre-alpha software; interfaces and data models may still change.
- Chat responses are not streamed; a reply arrives when generation finishes.
- No meal-level food logging or nutrition database; nutrition support is calculators plus retrieval and chat.
- Answers can be wrong or incomplete and are not medical advice.
- Retrieval quality depends on the documents you provide; this repository does not ship a curated knowledge base.
- The production layout is a single instance with in-process rate limiting and ingestion.
- Reranking is optional and disabled by default.
- Some pinned AI libraries (LangGraph / LangChain Core) have known advisories awaiting a major upgrade; see the audit.
Possible improvements (not implemented)
- Token streaming for chat.
- Shared rate-limit storage for multi-instance deployment.
- Upgrading the LangGraph / LangChain stack.
- Cookie-based sessions instead of browser-stored tokens.
- Food logging and richer nutrition data.
| Document | Contents |
|---|---|
docs/setup.md |
Detailed local development runbook |
docs/deployment.md |
Docker, Render, Vercel, migrations, troubleshooting |
docs/api.md |
API conventions (the generated reference is at /docs) |
docs/models.md |
Models and why each is used |
docs/extraction.md |
Structured fact extraction |
docs/chroma-to-pgvector-migration.md |
Moving an existing ChromaDB store to pgvector |
docs/SECURITY_AUDIT.md |
Security audit, residual risks, platform settings |
Contributions are welcome. See CONTRIBUTING.md for the workflow and checks, and
AGENTS.MD for architecture conventions.
FitAI is released under the MIT License. Third-party services and models you connect (Groq, Supabase, Hugging Face and others) are governed by their own terms.
Built with FastAPI, React, Vite, Supabase, pgvector, ChromaDB, LangGraph, Groq, Hugging Face, SQLAlchemy and Pydantic. Hosted on Render and Vercel.

.png)
.png)
.png)
.png)
.png)
