Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/davidmpizarro/QuipuEco-Hackaton/llms.txt

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

Getting QuipuEco running locally takes about five minutes. The project ships as two separate services that must run simultaneously: a React + Vite frontend on port 5173 and a FastAPI backend on port 8000. The frontend calls the backend directly at http://localhost:8000 — no reverse proxy or environment switching needed for local development.

​
Prerequisites

Before you begin, make sure you have the following tools and credentials ready:

Node.js 18+

Required to run the Vite dev server and install frontend dependencies. Download from nodejs.org.

Python 3.11+

Required for the FastAPI backend. Use pyenv or the official installer.

Google AI Studio API Key

Free tier available at aistudio.google.com. QuipuEco uses the gemini-3.1-flash-lite model.

Mapbox Access Token

Create a free account at mapbox.com and generate a public token from the dashboard.

​
Setup Steps

1
Clone the Repository
2
git clone https://github.com/davidmpizarro/QuipuEco-Hackaton.git
cd QuipuEco-Hackaton
3
The repository contains the frontend in the project root and expects the backend to be in a sibling quipueco-backend/ directory. Check the README for the latest backend repo link if it lives in a separate repository.
4
Install Frontend Dependencies
5
Navigate to the frontend directory and install packages. The project uses pnpm as its primary package manager, but npm and yarn work equally well.
6
pnpm
cd quipueco-frontend
pnpm install
npm
cd quipueco-frontend
npm install
yarn
cd quipueco-frontend
yarn install
7
Then create a .env file in the quipueco-frontend/ root with your Mapbox token:
8
# quipueco-frontend/.env
VITE_MAPBOX_TOKEN=your_mapbox_token_here
9
Vite exposes only variables prefixed with VITE_ to the browser bundle. Any other environment variables in .env will be ignored by the frontend at runtime.
10
Set Up the Python Backend
11
In a new terminal, navigate to the backend directory, create a virtual environment, and install dependencies:
12
cd quipueco-backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
13
Then create a .env file in the quipueco-backend/ root with your Gemini API key:
14
# quipueco-backend/.env
GEMINI_API_KEY=your_gemini_api_key_here
15
Start the Frontend Dev Server
16
From the quipueco-frontend/ directory, start Vite:
17
pnpm
pnpm run dev
npm
npm run dev
yarn
yarn dev
18
The app will be available at http://localhost:5173.
19
Start the FastAPI Backend
20
From the quipueco-backend/ directory (with the virtual environment active), start uvicorn:
21
uvicorn app.main:app --reload
22
The API will be available at http://localhost:8000. The --reload flag enables hot-reloading on code changes.
23
You can verify the backend is running by opening the auto-generated API docs at http://localhost:8000/docs.
24
Test the Full Flow
25
With both services running, open http://localhost:5173 in Chrome (required for Web Speech API support).
26
  • The QuipuEco splash screen loads, then transitions to the main Clasificar tab.
  • Tap Subir foto and select a photo of a plastic bottle (or any waste item).
  • Tap Clasificar Residuo — the image is sent to POST /clasificar.
  • Within ~2 seconds, the ClassificationResult view appears with the material type, CO₂ savings, preparation instructions, and a link to the nearest collection points.
  • Tap the 🎙 Agente QuipuEco button and ask a question like “¿Dónde lo llevo?” — the voice agent calls POST /chat and responds in audio.
    • Both services must run simultaneously. The frontend hardcodes http://localhost:8000 as the API base URL in both ImageCapture.jsx and AgenteVoz.jsx. If the backend is not running, all classification and chat requests will fail silently with a connection error message displayed in the UI.

    ​
    Verifying the API Endpoints

    Once the backend is running, you can test both endpoints directly using curl or the FastAPI Swagger UI at http://localhost:8000/docs: Classify a waste item from an image: 
    curl -X POST http://localhost:8000/clasificar \
  -F "file=@/path/to/bottle.jpg"
    Expected response shape: 
    {
  "nombre": "botella de plástico PET",
  "tipo": "plastico",
  "instrucciones": "Retira la tapa, enjuaga bien y aplástala...",
  "punto_acopio": "Tiendas Tambo",
  "co2_evitado_kg": 0.12,
  "peso_estimado_kg": 0.03,
  "consejo": "Cada botella reciclada evita...",
  "respuesta_voz": "He clasificado una botella de plástico PET..."
}
    Send a conversational message to the voice agent: 
    curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "mensaje": "¿Cuál es el Tambo más cercano?",
    "historial": [],
    "contexto_residuo": null,
    "lat": -12.0464,
    "lng": -77.0428
  }'
    Expected response shape: 
    {
  "respuesta": "El Tambo más cercano es Tambo Riva Agüero en El Agustino...",
  "accion": "mapa",
  "accion_data": "plastico",
  "punto_cercano": "Tambo Riva Agüero - El Agustino"
}

    ​
    Mobile Testing

    To test the PWA on a real mobile device, find your machine’s local IP address (e.g., 192.168.1.42) and open http://192.168.1.42:5173 in Chrome on the phone. Both devices must be on the same Wi-Fi network. The Vite dev server binds to 0.0.0.0 by default, so no extra configuration is needed. On mobile, you can also add the app to your home screen via Chrome’s “Add to Home Screen” prompt for a full PWA experience.
    The Web Speech API (SpeechRecognition and SpeechSynthesis) is only fully supported in Chromium-based browsers (Chrome, Edge). Safari has partial support; Firefox does not support SpeechRecognition at all. For the best voice agent experience, use Chrome on both desktop and mobile.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us