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.

QuipuEco is split into two independently runnable processes — a React/Vite frontend and a FastAPI Python backend — each of which requires its own .env file before it can start correctly. The frontend needs a Mapbox access token to render the interactive recycling-point map, while the backend needs a Google Gemini API key to power both image classification and the conversational voice agent. Neither file is committed to version control, and neither token should ever be shared between the two processes or embedded in source code.

​
Overview

Frontend .env

Lives in quipueco-frontend/ (the project root). Exposes variables to Vite at build time via the VITE_ prefix. Contains VITE_MAPBOX_TOKEN.

Backend .env

Lives in quipueco-backend/. Loaded by Python’s python-dotenv at runtime. Contains GEMINI_API_KEY.

​
Creating the environment files

1

Create the frontend environment file

In the quipueco-frontend/ directory (the repository root), create a file named .env:
# quipueco-frontend/.env
VITE_MAPBOX_TOKEN=your_mapbox_token_here
Replace your_mapbox_token_here with a real token starting with pk.. See Mapbox Configuration for how to obtain one.Vite automatically reads .env files in the project root at dev-server startup. Variables must be prefixed with VITE_ to be accessible in browser-side code.
2

Create the backend environment file

In the quipueco-backend/ directory, create a file named .env:
# quipueco-backend/.env
GEMINI_API_KEY=your_gemini_api_key_here
Replace your_gemini_api_key_here with a real key starting with AIza. See Gemini AI Configuration for how to obtain one.
3

Start the backend server

cd quipueco-backend
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload
The FastAPI server will be available at http://localhost:8000. The --reload flag enables hot-reloading during development.
4

Start the frontend dev server

In a separate terminal:
cd quipueco-frontend
npm install
npm run dev
Vite will serve the app at http://localhost:5173 and automatically inject VITE_MAPBOX_TOKEN into the build.

​
Variable reference

​
Frontend variables

VariableRequiredDescription
VITE_MAPBOX_TOKEN✅ YesMapbox public access token. Must start with pk.. Used by VistaMapaPuntos.jsx to initialize the map and fetch walking routes.
The token is accessed in the Vite application like this:
src/components/VistaMapaPuntos.jsx
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN;
Any variable not prefixed with VITE_ is intentionally stripped from the client bundle by Vite, preventing accidental secret exposure.

​
Backend variables

VariableRequiredDescription
GEMINI_API_KEY✅ YesGoogle AI Studio API key. Must start with AIza. Used by both the /clasificar and /chat endpoints.

​
API URL configuration

The backend URL is currently hardcoded as a constant in two frontend source files: 
const API_URL = "http://localhost:8000";
This means both the image classification flow and the voice agent point to the same local FastAPI instance. If you need to change the backend URL — for example when deploying to a staging or production environment — update the API_URL constant in both files.
To make the backend URL environment-driven rather than hardcoded, you can add a VITE_API_URL variable to the frontend .env file and replace the hardcoded string with import.meta.env.VITE_API_URL in both components.

​
Port defaults

ServiceDefault portStart command
Vite frontend5173npm run dev
FastAPI backend8000uvicorn app.main:app --reload
Both servers must be running simultaneously for the app to function. The frontend makes cross-origin requests to the backend; ensure your backend has CORS configured to accept requests from http://localhost:5173 during local development.

​
Security

Never commit .env files to Git. Both quipueco-frontend/.env and quipueco-backend/.env are already listed in .gitignore. Committing them would expose your Mapbox token and Gemini API key in the repository’s history, where they can be scraped by automated tools even after deletion.If you accidentally commit a secret, rotate the affected key immediately — in your Mapbox account or Google AI Studio — before pushing any further.
The VITE_MAPBOX_TOKEN is a public token by design — Mapbox access tokens are intended to be embedded in browser-side code and can be scoped to specific URLs in the Mapbox dashboard. However, they should still be kept out of version control. The GEMINI_API_KEY is a private secret and must never appear in any frontend code, build output, or public repository.

Build docs developers (and LLMs) love

Get started for freeTalk to us