Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/elzackarias/Hackaton3B-Reto1/llms.txt

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

This guide walks you through cloning the repository, installing all Python and Node.js dependencies, launching the FastAPI + Socket.IO backend, starting the React dashboard, and sending your first test events — all without needing a trained YOLO model or a physical camera. By the end you will have a live inventory feed running in your browser.

​
Prerequisites

Before you begin, make sure the following are available on your machine:
  • Python 3.10+ — required for FastAPI, Ultralytics, and all backend modules
  • Node.js 18+ — required for the Vite-based React frontend
  • A USB camera or RTSP stream — needed for live inference; mock endpoints work without one
  • git — to clone the repository
1

Clone the repository

Open a terminal and run:
git clone https://github.com/elzackarias/Hackaton3B-Reto1.git
cd Hackaton3B-Reto1
This clones the full monorepo containing backend/, frontend/, scripts/, and assets/.
2

Install all dependencies

A single setup script handles both the Python virtual environment (under backend/.venv) and the Node.js packages (under frontend/node_modules). Run the variant matching your OS:
./scripts/setup-all.sh
The script runs in two stages: PASO 1/2 installs Python dependencies from backend/requirements.txt into the virtual environment, and PASO 2/2 runs npm install in the frontend/ directory.
3

Start the backend server

Activate the virtual environment and launch Uvicorn. The ASGI app exported from main.py is called combined_app — it wraps both FastAPI and the Socket.IO server into a single ASGI application:
cd backend
source .venv/bin/activate        # Linux / macOS
# .venv\Scripts\Activate.ps1     # Windows PowerShell

uvicorn main:combined_app --host 0.0.0.0 --port 8000 --reload
On startup the backend will:
  1. Initialize all engine instances (InventoryEngine, PredictionEngine, HeatmapEngine, NarrativeEngine).
  2. Register observer callbacks so M6, M7, and M8 react to every inventory event.
  3. Attempt to start the camera pipeline in a background thread (auto-retries with exponential backoff if no camera is found).
  4. Expose the Swagger UI at http://localhost:8000/docs.
The first inference call after startup is noticeably slower than subsequent ones. This is expected: DetectionEngine.__init__ deliberately runs 3 dummy inferences on a blank 640×640 frame to warm up the YOLO model and CUDA/CPU kernels before any real video is processed.
4

Start the React dashboard

In a second terminal, from the project root:
cd frontend
npm run dev
Vite starts the development server. The project’s vite.config.ts sets the port to 3000 — open http://localhost:3000 in your browser.
If you only want a quick sanity check without running the full React frontend, the backend ships a self-contained HTML dashboard at http://localhost:8000/dashboard. It polls the REST API every 3 seconds, shows live KPIs and inventory cards for all 7 SKUs, and renders the priority restock table. No Node.js required.
5

Verify both services are running

URLWhat you should see
http://localhost:3000React dashboard with live Socket.IO connection indicator
http://localhost:8000/docsSwagger UI listing all REST endpoints
http://localhost:8000/api/health{"status": "ok", "uptime": <seconds>}
http://localhost:8000/dashboardEmbedded HTML inventory dashboard
6

Trigger a test event via the mock endpoint

The /api/mock/event endpoint picks a random SKU and injects a RETIRO (removal) event into the inventory engine — no camera or YOLO model needed:
curl -X POST http://localhost:8000/api/mock/event
A successful response looks like this:
{
  "status": "ok",
  "event": {
    "event_id": "3f2e1a4b-...",
    "event_type": "retiro",
    "sku_id": "nachos_naturasol",
    "sku_name": "Nachos Con Sal Naturasol 200 gr",
    "slot_id": 4,
    "stock_before": 8,
    "stock_after": 7,
    "confidence": 0.95,
    "timestamp": "2026-03-21T14:32:01.123456"
  }
}
If you have the React dashboard open you will see the stock card for the chosen SKU decrement in real time — the event travels through InventoryEngine → observer callbacks → Socket.IO broadcast → React state update.
If stock for the randomly chosen SKU is already at 0, the endpoint returns {"status": "ignored", "message": "Evento ignorado (stock en 0 o duplicado)"} — this is expected behaviour, not an error. Use POST /api/inventory/reset to restore all stocks to 8 before re-running.
7

Simulate a specific product removal

Use POST /api/events to inject an event for a named SKU and event type. The event_type field accepts "retiro" (removal) or "devolucion" (return):
curl -X POST http://localhost:8000/api/events \
  -H 'Content-Type: application/json' \
  -d '{"sku_id": "nachos_naturasol", "event_type": "retiro", "confidence": 0.95}'
You can also simulate a return — for example, putting a product back on the shelf:
curl -X POST http://localhost:8000/api/events \
  -H 'Content-Type: application/json' \
  -d '{"sku_id": "nachos_naturasol", "event_type": "devolucion", "confidence": 0.92}'
Both requests return the resulting InventoryEvent object and simultaneously push an inventory_update Socket.IO message to all connected dashboard clients.

​
What Happens Next

Once both services are running and events are flowing, the dashboard updates in real time across all connected tabs:
  • Stock cards turn yellow (≤ 50 %) or red (≤ 20 %) as units are removed.
  • Narrative panel shows auto-generated Spanish messages such as “Nachos Naturasol retirado del slot 4. Stock: 7”.
  • Predictions panel displays estimated minutes to depletion once at least 2 removal events have occurred for a SKU.
  • Heatmap highlights the most-interacted slots within the configured time window (default: last 5 minutes).
To reset all stocks back to 8 units before running a fresh demo: 
curl -X POST http://localhost:8000/api/inventory/reset

Build docs developers (and LLMs) love

Get started for freeTalk to us