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.

FridgeRadar’s backend is a fully asynchronous REST API built with FastAPI 0.111, SQLAlchemy 2.0 (async), and aiomysql, designed to run on Python 3.12. It handles authentication (JWT + bcrypt), household inventory management, scheduled semáforo recalculation via APScheduler, and 13 resource endpoints across the /api/v1 prefix.

​
Requirements

Python 3.12+

The backend uses match statements, asyncio improvements, and type annotation syntax available only in 3.12+.

MySQL 8+

Required for utf8mb4, window functions, generated columns, and MySQL Events used by the semáforo scheduler.

Running MySQL Instance

The backend connects at startup — ensure MySQL is accessible before launching uvicorn.

​
Setup and Installation

1

Clone the repository and enter the backend directory

git clone <repo-url>
cd fridgeradar/backend
2

Create and activate a virtual environment

python -m venv venv

# Linux / macOS
source venv/bin/activate

# Windows
venv\Scripts\activate
3

Install Python dependencies

All pinned runtime dependencies (FastAPI, SQLAlchemy, aiomysql, APScheduler, pydantic-settings, uvicorn, etc.) are listed in requirements.txt:
pip install -r requirements.txt
Key packages installed:
PackageVersionPurpose
fastapi0.111.0ASGI web framework
uvicorn0.29.0ASGI server
sqlalchemy2.0.36Async ORM
aiomysql0.2.0Async MySQL driver
APScheduler3.10.4Background task scheduler
pydantic2.7.1Request/response validation
pydantic-settings2.2.1.env-based configuration
python-jose3.3.0JWT token signing
bcrypt4.0.1Password hashing
4

Configure environment variables

Copy the example file and edit it with your credentials:
cp .env.example .env
All variables recognized by app/core/config.py:
# Application
APP_NAME=FridgeRadar
APP_VERSION=1.0.0
DEBUG=False                          # Set True only in development

# Database — MySQL 8+
DB_HOST=localhost
DB_PORT=3306
DB_NAME=fridgeradar_db
DB_USER=root
DB_PASSWORD=your_mysql_password

# Authentication
SECRET_KEY=replace-with-a-secure-random-string
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440     # 24 hours

# CORS — list all allowed frontend origins
ALLOWED_ORIGINS=["https://your-frontend-domain.com"]

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

# APScheduler timezone (IANA format)
SCHEDULER_TIMEZONE=America/Lima
Never deploy with the default SECRET_KEY (cambia-esto-en-produccion). Generate a secure value before going live:
python -c "import secrets; print(secrets.token_hex(32))"
5

Initialize the database schema

Before starting the API, load the full schema into MySQL:
mysql -u root -p < backend/infra/mysql/fridgeradar_db.sql
See the Database page for a complete description of what this script creates.
6

Start the API server

Development — with hot reload:
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Or use the convenience script (which does the same thing from the correct working directory):
bash backend/infra/scripts/start_dev.sh
Production — multiple workers, reload disabled:
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
Set DEBUG=False in .env for all production deployments. In debug mode, tracebacks are included in API error responses.

​
Verifying the Deployment

​
Health Check

Once the server is running, confirm it is healthy: 
curl http://localhost:8000/health
Expected response: 
{"status": "ok", "app": "FridgeRadar"}

​
Interactive API Documentation

FridgeRadar exposes two self-hosted API documentation UIs automatically:

Swagger UI

Full interactive documentation at /docs. Try any endpoint directly from the browser, including authenticated routes after supplying a Bearer token.

ReDoc

Clean, readable reference documentation at /redoc. Ideal for sharing with frontend teams or external integrators.

​
CORS Configuration

The backend reads allowed origins from the ALLOWED_ORIGINS environment variable, which maps to Settings.ALLOWED_ORIGINS in app/core/config.py (a list[str]). 
# Development — Vite dev server
ALLOWED_ORIGINS=["http://localhost:5173"]

# Production — replace with your actual frontend domain
ALLOWED_ORIGINS=["https://app.yourfridgeradar.com"]

# Multiple origins
ALLOWED_ORIGINS=["https://app.yourfridgeradar.com","https://www.yourfridgeradar.com"]
The value must be valid JSON — use double quotes inside the list. If the frontend and backend are served from the same domain through a reverse proxy, you can omit the CORS configuration entirely.

​
API Endpoints Reference

MethodRouteDescription
POST/api/v1/auth/loginAuthenticate; returns JWT access token
POST/api/v1/auth/registerRegister a new user
GET / PUT / DELETE/api/v1/usuarios/{id}User profile CRUD
GET / POST/api/v1/hogaresHousehold management
GET / POST/api/v1/zonasStorage zones within a household
GET / POST / PATCH / DELETE/api/v1/estantesShelf CRUD; supports ?id_zona= filter
GET / POST/api/v1/inventario/{id_hogar}Household inventory; supports ?estado=rojo filter
GET / POST/api/v1/productosGlobal product catalog
GET/api/v1/recetasAvailable recipes
GET/api/v1/alertasUnread alerts for the authenticated user
GET / POST/api/v1/listas-compraShopping lists
GET/api/v1/desperdicioWaste report
GET/api/v1/semaforoFood freshness semáforo status
GET/api/v1/tengo-hambreRecipe suggestions using soon-to-expire items

​
Testing

Run the full test suite with coverage: 
cd backend
pytest --cov=app tests/
Run only unit tests: 
pytest tests/unit/ -v
Run only integration tests: 
pytest tests/integration/ -v
Integration tests require a live MySQL connection. Ensure your .env points to a test database before running them.

​
Linting and Type Checking

The project uses ruff for fast linting and mypy for static type analysis, both configured in pyproject.toml targeting Python 3.12. 
# Lint with ruff (line length 100, rules: E, F, I, N, UP)
ruff check app/

# Auto-fix safe violations
ruff check app/ --fix

# Static type checking with mypy
mypy app/

Build docs developers (and LLMs) love

Get started for freeTalk to us