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 configured entirely through environment variables, which are loaded at startup by a pydantic-settings BaseSettings class defined in backend/app/core/config.py. Pydantic validates types and applies defaults automatically, so the app will refuse to start if a required variable is missing or malformed. In development, values are read from a backend/.env file; in production, inject them as real environment variables in your deployment environment — no .env file is needed or recommended.

​
Environment Variables

​
Application

​
APP_NAME
string
default:"FridgeRadar"
The display name of the application. This value is used as the FastAPI title property, which appears in the Swagger UI header and in the /health endpoint response ({"status":"ok","app":"FridgeRadar"}).
​
APP_VERSION
string
default:"1.0.0"
Semantic version string surfaced in the FastAPI OpenAPI schema. Increment this when you deploy a new release so clients can detect API version changes.
​
DEBUG
boolean
default:"False"
When True, FastAPI enables more verbose tracebacks in error responses and the Uvicorn reloader is typically active. Never set this to True in production.

​
Database

FridgeRadar uses SQLAlchemy 2.0 with the aiomysql async driver. The five variables below are combined at runtime into the async connection URL: mysql+aiomysql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}.
​
DB_HOST
string
default:"localhost"
Hostname or IP address of the MySQL 8 server. Use host.docker.internal when running the backend in Docker but MySQL on the host machine.
​
DB_PORT
integer
default:"3306"
TCP port MySQL is listening on. Only change this if your MySQL instance uses a non-standard port.
​
DB_NAME
string
default:"fridgeradar_db"
Name of the MySQL database to connect to. This must match the schema created by backend/infra/mysql/fridgeradar_db.sql.
​
DB_USER
string
default:"root"
MySQL username. For production, create a dedicated user with only the privileges required (SELECT, INSERT, UPDATE, DELETE, EXECUTE on the fridgeradar_db schema).
​
DB_PASSWORD
string
default:"admin"
Password for DB_USER. The default value admin is intentionally insecure — always override it in every environment, including local development.

​
JWT Authentication

​
SECRET_KEY
string
default:"cambia-esto-en-produccion"
The HMAC signing secret used to sign and verify JWT tokens. The default value in .env.example is cambia-esto-por-algo-seguro-en-produccion (Spanish for “change this to something secure in production”) — this is a placeholder and must be replaced before the app handles any real user data. Generate a strong value with openssl rand -hex 32.
​
ALGORITHM
string
default:"HS256"
JWT signing algorithm. HS256 (HMAC-SHA256) is the default and is appropriate for single-server deployments. If you need asymmetric signing (e.g., RS256) for a multi-service architecture, change this value and update the key handling in app/core/security.py.
​
ACCESS_TOKEN_EXPIRE_MINUTES
integer
default:"1440"
Lifetime of issued access tokens in minutes. The default of 1440 equals exactly 24 hours (1 day). Reduce this for higher-security environments and implement token refresh accordingly.

​
CORS

​
ALLOWED_ORIGINS
string
default:"[\"http://localhost:5173\"]"
A JSON-encoded array of origin URLs that the browser is permitted to make cross-origin requests from. The default allows only the local Vite dev server. See the CORS section below for details on setting multiple origins.

​
Semáforo Thresholds

​
SEMAFORO_AMARILLO_DIAS
integer
default:"7"
Number of days before expiry at which an inventory item transitions from verde (fresh) to amarillo (use soon). Items with expiry_date - today <= SEMAFORO_AMARILLO_DIAS are classified as yellow. See the Semáforo Thresholds section below.
​
SEMAFORO_ROJO_DIAS
integer
default:"2"
Number of days before expiry at which an item escalates from amarillo to rojo (urgent). Items with expiry_date - today <= SEMAFORO_ROJO_DIAS are classified as red. Must be less than SEMAFORO_AMARILLO_DIAS.

​
Scheduler

​
SCHEDULER_TIMEZONE
string
default:"America/Lima"
IANA timezone string used by APScheduler when calculating cron trigger times for the daily semáforo recalculation and expiry alert jobs. Set this to the timezone of your household or server location (e.g., America/New_York, Europe/Madrid, Asia/Tokyo).

​
Example .env File

The following is the complete backend/.env.example file shipped with the repository. Copy it to backend/.env and fill in the values marked with comments. 
# Application
APP_NAME=FridgeRadar
APP_VERSION=1.0.0
DEBUG=True

# Database
DB_HOST=localhost
DB_PORT=3306
DB_NAME=fridgeradar_db
DB_USER=root
DB_PASSWORD=admin

# JWT — CHANGE THIS before handling real data
SECRET_KEY=cambia-esto-por-algo-seguro-en-produccion
ACCESS_TOKEN_EXPIRE_MINUTES=1440

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

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

# Scheduler timezone (IANA format)
SCHEDULER_TIMEZONE=America/Lima
Never commit backend/.env to version control. It is already listed in .gitignore, but double-check before every commit. In CI/CD pipelines and production deployments, inject secrets as environment variables via your platform’s secrets manager (AWS Secrets Manager, GitHub Actions secrets, Docker secrets, etc.) rather than copying a .env file.Pay particular attention to SECRET_KEY and DB_PASSWORD. A leaked SECRET_KEY allows an attacker to forge valid JWT tokens for any user in your system.Generate a production-grade SECRET_KEY with:
openssl rand -hex 32

​
CORS Configuration

The ALLOWED_ORIGINS variable is parsed by pydantic-settings as a list[str], but .env files are plain text — so the value must be a valid JSON array string. Single origin (default for local dev): 
ALLOWED_ORIGINS=["http://localhost:5173"]
Multiple origins (e.g., staging + production frontend): 
ALLOWED_ORIGINS=["https://app.fridgeradar.io", "https://staging.fridgeradar.io"]
The value is passed directly to FastAPI’s CORSMiddleware as the allow_origins list, with allow_credentials=True, allow_methods=["*"], and allow_headers=["*"]. If you need to restrict methods or headers, edit backend/app/main.py accordingly.
During local development, if your frontend runs on a port other than 5173 (for example because Vite selected a fallback port), update ALLOWED_ORIGINS to match. A CORS error in the browser console almost always means the origin in the request doesn’t appear in this list.

​
Semáforo Thresholds

The semáforo (traffic-light) system is the heart of FridgeRadar’s freshness logic. Two thresholds control the boundaries between the four states: 
Today ──────────────────────────────────► Expiry Date
         rojo          amarillo    verde
  ◄────────────────┤────────────────┤──────►
              ROJO_DIAS       AMARILLO_DIAS
               (2 days)        (7 days)
ConditionStateColour
days_until_expiry > SEMAFORO_AMARILLO_DIASverde🟢 Fresh
SEMAFORO_ROJO_DIAS < days_until_expiry <= SEMAFORO_AMARILLO_DIASamarillo🟡 Use soon
0 < days_until_expiry <= SEMAFORO_ROJO_DIASrojo🔴 Urgent
days_until_expiry <= 0vencido⚫ Expired
The thresholds are recalculated daily by the APScheduler background task. You can also trigger an immediate recalculation by querying /api/v1/semaforo. Adjusting for your household: If your household consumes food quickly and seven days feels too cautious for the yellow warning, lower SEMAFORO_AMARILLO_DIAS to 3 or 4. Conversely, if you want more lead time to act, raise it to 10 or 14. The only constraint is SEMAFORO_ROJO_DIAS < SEMAFORO_AMARILLO_DIAS. 
# Example: tighter thresholds for a fast-consuming household
SEMAFORO_AMARILLO_DIAS=4
SEMAFORO_ROJO_DIAS=1

Build docs developers (and LLMs) love

Get started for freeTalk to us