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 is an open-source, full-stack household pantry management application designed around a single goal: eliminating food waste before it happens. Rather than relying on memory or manual checks, FridgeRadar continuously monitors every item in your pantry, classifies its freshness using a traffic-light system called the semáforo, and proactively surfaces recipe suggestions built from ingredients that are closest to expiring — so nothing gets thrown away when it could still become dinner.

​
What FridgeRadar Does

At its core, FridgeRadar solves the gap between buying groceries and actually using them. Every product added to inventory is assigned an expiry date and automatically slotted into one of four semáforo states:
StateColourMeaning
verde🟢 GreenFresh — more than 7 days until expiry
amarillo🟡 YellowUse soon — within 7 days of expiry
rojo🔴 RedUrgent — within 2 days of expiry
vencido⚫ ExpiredPast expiry date
The thresholds for amarillo and rojo are fully configurable via environment variables (see Configuration). APScheduler runs background tasks daily to recalculate semáforo states, fire expiry alerts, and update waste-tracking records automatically.

​
Tech Stack

FridgeRadar is split into a Python backend and a React frontend that communicate over a proxied REST API. Backend
  • FastAPI 0.111 — async HTTP framework with auto-generated OpenAPI docs
  • Python 3.12 — latest stable runtime
  • SQLAlchemy 2.0 (async) — ORM with aiomysql driver
  • MySQL 8 — primary relational database
  • APScheduler 3.10 — cron-style background scheduler for semáforo recalculation and expiry alerts
  • Pydantic v2 + pydantic-settings — request/response validation and typed configuration
  • JWT (python-jose) + bcrypt — stateless authentication
Frontend
  • React 18.3 — component-based UI
  • Vite 5.4 — lightning-fast dev server on port 5173
  • React Router 6 — client-side routing
  • Axios 1.7 — HTTP client; all /api requests are proxied to the backend at localhost:8000

​
Key Features

Semáforo Freshness System

Automatic four-state traffic-light classification (verde → amarillo → rojo → vencido) with configurable day thresholds recalculated daily by the scheduler.

Household & Zone Management

Organise your home into a Household → Zone → Shelf hierarchy so every item knows exactly where it lives and who owns it.

Inventory Tracking

Add products by barcode or name, set quantities and expiry dates, filter by semáforo state, and let the system do the rest.

Recipes & Suggestions

Hit /api/v1/tengo-hambre to get recipe suggestions built exclusively from your ingredients that are yellow or red on the semáforo — cook what’s expiring first.

Waste Tracking

Every expired or discarded item is logged. Pull the /api/v1/desperdicio report to see waste trends over time and act on them.

Shopping Lists & Alerts

Automatically generated alerts notify household members when items are about to expire, and shopping lists help you restock only what you need.

​
Interactive API Documentation

FridgeRadar’s FastAPI backend generates live, interactive documentation from the OpenAPI schema. No separate tool installation is required.
Once the backend is running locally, open Swagger UI at http://localhost:8000/docs to try every endpoint in your browser, or visit Redoc at http://localhost:8000/redoc for a clean, read-only reference layout.

​
Architecture Overview

FridgeRadar models a household’s physical storage as a strict four-level hierarchy. Understanding this structure is essential before adding your first inventory item. 
Household (Hogar)
└── Zone (Zona)          ← e.g. Kitchen, Garage, Basement
    └── Shelf (Estante)  ← e.g. Top shelf, Freezer drawer
        └── Inventory Item (Inventario)
            ├── Product reference
            ├── Quantity & unit
            ├── Expiry date
            └── Semáforo state (verde / amarillo / rojo / vencido)
A Household is the top-level owner entity — every user belongs to one or more households. Inside a household, Zones represent physical areas of the home. Each Zone contains one or more Shelves, which act as the direct containers for Inventory records. This nesting means you can ask questions like “show me everything red on the kitchen top shelf” with a single filtered API call to /api/v1/inventario/{id_hogar}?estado=rojo. The backend exposes 13 endpoint groups across 19 SQLAlchemy models, all prefixed under /api/v1. Authentication is JWT-based — every protected route requires a Bearer token obtained from /api/v1/auth/login.

Build docs developers (and LLMs) love

Get started for freeTalk to us