Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/EstefanoARG/FridgeRadar/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through every step needed to run FridgeRadar on your local machine — from cloning the repository to verifying the health endpoint and browsing the interactive API docs. The whole process takes about ten minutes, assuming you already have the prerequisites installed.

​
Prerequisites

Before you begin, make sure the following are available on your system:
  • Python 3.12+ — python --version should return 3.12.x or higher
  • MySQL 8+ — a running instance with a user that has CREATE DATABASE privileges
  • Node.js 18+ — required by Vite and the React frontend (node --version)

​
Setup Steps

1

Clone the repository

Pull the source code from GitHub and move into the project root.
git clone https://github.com/EstefanoARG/FridgeRadar.git && cd FridgeRadar
2

Create a Python virtual environment and install dependencies

Isolate the backend’s Python dependencies in a virtual environment, then install everything from requirements-dev.txt.
# Create and activate the virtual environment
python -m venv venv
source venv/bin/activate        # Linux / macOS
# venv\Scripts\activate         # Windows PowerShell

# Install backend dependencies
cd backend
pip install -r requirements-dev.txt
Key packages installed include FastAPI 0.111, SQLAlchemy 2.0 with aiomysql, APScheduler 3.10, pydantic-settings 2.2, python-jose for JWT, and bcrypt for password hashing.
3

Configure environment variables

Copy the provided example file and fill in your local MySQL credentials.
cp backend/.env.example backend/.env
Open backend/.env in your editor and set at minimum the database credentials and a strong secret key:
# Application
APP_NAME=FridgeRadar
APP_VERSION=1.0.0
DEBUG=True

# Database — update these to match your MySQL setup
DB_HOST=localhost
DB_PORT=3306
DB_NAME=fridgeradar_db
DB_USER=root
DB_PASSWORD=your_mysql_password

# JWT — replace with a long random string in production
SECRET_KEY=cambia-esto-por-algo-seguro-en-produccion
ACCESS_TOKEN_EXPIRE_MINUTES=1440

# CORS
ALLOWED_ORIGINS=["http://localhost:5173"]

# Semáforo thresholds (days)
SEMAFORO_AMARILLO_DIAS=7
SEMAFORO_ROJO_DIAS=2

# Scheduler
SCHEDULER_TIMEZONE=America/Lima
The six variables you must review are DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, and SECRET_KEY. All others have sensible defaults and can be left unchanged for local development. See Configuration for the full reference.
4

Create the database

Run the bundled SQL script to create the fridgeradar_db schema, including all 19 tables, indexes, triggers, stored procedures, views, and seed data (product categories, recipe tags).
# Run from the repository root
mysql -u root -p < backend/infra/mysql/fridgeradar_db.sql
Enter your MySQL root password when prompted. The script is idempotent — it uses CREATE DATABASE IF NOT EXISTS and CREATE TABLE IF NOT EXISTS guards throughout.
5

Start the backend

Launch the FastAPI application with Uvicorn in reload mode so changes to source files are picked up automatically.
cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
You should see output similar to:
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Application startup complete.
6

Start the frontend

In a new terminal, install the Node dependencies and start the Vite dev server. All requests to /api/* are automatically proxied to the backend at localhost:8000.
cd frontend
npm install
npm run dev
Vite will print:
VITE v5.4.x  ready in Xms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
Open http://localhost:5173 in your browser to access the FridgeRadar UI.

​
Verify the Backend is Healthy

With the backend running, confirm the health endpoint responds correctly: 
curl http://localhost:8000/health
Expected response: 
{"status": "ok", "app": "FridgeRadar"}
A 200 OK with that JSON body means the FastAPI app started successfully and is connected to the scheduler. If you see a database connection error instead, double-check the DB_* values in backend/.env.
Interactive API docs are live at two URLs:Both are generated automatically from the OpenAPI schema and stay in sync with the code.

​
Next Steps

Authentication

Register a user, obtain a JWT token from /api/v1/auth/login, and learn how to pass it as a Bearer header on protected routes.

Inventory Concepts

Understand how the Household → Zone → Shelf → Inventory hierarchy works and how to add your first products with expiry dates.

API Overview

Browse all 13 endpoint groups, understand pagination and filtering, and learn how to filter inventory by semáforo state.

Build docs developers (and LLMs) love

Get started for freeTalk to us