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’s Tambo+ partnership transforms Lima’s largest convenience store chain into a citywide recycling infrastructure layer. Rather than asking residents to seek out dedicated recycling facilities — which are few, far between, and often closed — QuipuEco routes plastic, paper, and metal waste to the 6 Tambo+ stores already embedded in Lima Este neighbourhoods. The moment Gemini classifies a material as plastico, papel, or metal, VistaMapaPuntos swaps its points layer to TAMBO_REAL_LIMA_ESTE, renders Tambo-branded markers on the Mapbox map, and sorts all 6 locations by Haversine distance from the user’s GPS position — turning a recycling decision into a 30-second navigation action.

​
Why Tambo+?

Tambo+ is Peru’s largest convenience store chain, operating 2,000+ locations nationwide, with stores open early morning to late night across every major Lima district. For Lima’s residents, Tambo is already part of the daily routine — groceries, phone top-ups, and quick meals all happen there. QuipuEco leverages that existing footfall rather than asking residents to adopt a new behaviour pattern.

No Appointment

Drop materials directly at the counter — no scheduling, no registration, no waiting period.

Long Hours

Tambo stores are open early to late, covering commute windows that municipal recycling points miss.

Dense Coverage

6 pilot locations span La Molina, Santa Anita, Ate, Chaclacayo, El Agustino, and Chosica — the core Lima Este districts.

​
Accepted Materials

Tambo+ accepts plastic, paper, and metal — the three material categories that can be handled safely at a convenience store counter without specialist equipment, refrigeration, or licensed disposal personnel.

Plástico ♳

Bottles, containers, packaging. Must be clean and dry before drop-off.

Papel / Cartón 📄

Paper, cardboard, and carton packaging. Flatten boxes to reduce volume at the counter.

Metal 🥫

Aluminium cans, tin cans, metal lids. Rinse and dry to avoid odours.
The Lima Este pilot covers 6 Tambo+ locations. Tambo operates 2,000+ stores nationwide — the same TAMBO_REAL_LIMA_ESTE data structure can be extended to any district as the program scales beyond the pilot.

​
Materials NOT Accepted at Tambo+

The following waste categories cannot be dropped off at Tambo+ stores. This is an operational constraint, not a design choice — each category requires specialist handling that a convenience store cannot provide.
Glass fragments pose a safety hazard to store staff and customers. Glass must be handled with protective equipment and transported in shatter-resistant containers. Tambo counters are not equipped for this. Redirect users to a Centro Verde municipal for glass drop-off.
Organic waste requires composting infrastructure, refrigerated short-term storage, or rapid collection to prevent pest attraction and odour. A retail counter environment cannot accommodate these requirements. Redirect to Centro Verde municipal composting programmes.
Electronic waste (RAEE — Residuos de Aparatos Eléctricos y Electrónicos) must be handled by certified RAEE managers under Peruvian environmental law (DS 009-2019-MINAM). No convenience store is authorised to receive or temporarily store these materials. Redirect to designated Centro Verde RAEE points.
Batteries, paint, chemicals, fluorescent bulbs, and similar materials require a licensed hazardous waste handler (gestor autorizado). Drop-off at an unlicensed point creates environmental liability. Redirect strictly to Centro Verde peligrosos locations with the appropriate authorisation.
Never instruct users to leave glass, organic, electronic, or hazardous materials at a Tambo+ counter. Doing so breaks operational agreements and undermines QuipuEco’s credibility with the Tambo partnership. The RED_POR_CATEGORIA map in VistaMapaPuntos.jsx enforces this routing automatically — only plastico, papel, and metal resolve to "tambo".

​
Operational Model

The drop-off flow is intentionally frictionless:
1

Classify with Gemini

The user photographs or describes their waste. The Gemini vision model returns a JSON classification with tipo: "plastico", "papel", or "metal".
2

Map loads Tambo layer

VistaMapaPuntos receives the classification result. detectarCategoria() resolves the type to "plastico", "papel", or "metal" — all three point to PUNTOS_LIMA.plastico / .papel / .metal, which are all set to TAMBO_REAL_LIMA_ESTE. Tambo-branded map markers appear.
3

Nearest store sorted automatically

If the user has granted geolocation, the Haversine algorithm sorts all 6 locations by walking distance. The closest store appears first in the bottom card rail.
4

User taps for walking or driving route

Tapping a store card calls the Mapbox Directions API and draws a route line on the map, showing estimated walking and driving time.
5

Drop off at the counter

The user brings clean, dry materials to the Tambo+ counter — no appointment, no form, no QR code required. The materials are handed directly to store staff (en el mostrador).
6

Eco-rank progresses

The classification and confirmed drop-off are logged via useHistorial, contributing CO₂ savings and kg recycled data to the user’s eco-rank progression: 🌱 Semilla Eco → 🌳 Árbol Joven → 🌍 Guardián Verde.

​
How QuipuEco Routes Users to Tambo

The routing logic lives entirely in src/components/VistaMapaPuntos.jsx. Three key data assignments drive the Tambo layer: 
// plastico, papel, and metal all share the same Tambo network.
// Drop-off is direct at the counter — no special handling needed.
PUNTOS_LIMA.plastico = TAMBO_REAL_LIMA_ESTE;
PUNTOS_LIMA.papel    = TAMBO_REAL_LIMA_ESTE;
PUNTOS_LIMA.metal    = TAMBO_REAL_LIMA_ESTE;
And the network badge mapping: 
const RED_POR_CATEGORIA = {
  plastico:    "tambo",
  papel:       "tambo",
  metal:       "tambo",
  organico:    "centro_verde",
  vidrio:      "centro_verde",
  electronico: "centro_verde",
  peligroso:   "centro_verde",
  general:     "centro_verde",
};
When red === "tambo", the map markers render a Tambo logo image instead of a material emoji, and the popup badge shows the Tambo branding. All other categories render Centro Verde markers. The voice agent can also trigger the Tambo layer directly. If a user says “¿Cuál es el Tambo más cercano?”, the conversational agent returns an accion_data string (e.g. "plastico") that is passed as puntoDestino to VistaMapaPuntos, pre-filtering the map to Tambo points without requiring a prior classification scan.

​
Scale Opportunity

The 6-store Lima Este pilot is a proof of concept for a much larger network:
StageStoresCoverage
Pilot (current)6Lima Este: La Molina, Santa Anita, Ate, Chaclacayo, El Agustino, Chosica
Lima Metro expansion~80–120All Lima districts via existing Tambo footprint
National rollout2,000+Peru-wide, using the same TAMBO_REAL_LIMA_ESTE data structure
Each new location requires only one additional object in the TAMBO_REAL_LIMA_ESTE array — no backend changes, no new components.
The TAMBO_REAL_LIMA_ESTE array is the single source of truth for all Tambo locations across plastico, papel, and metal. Adding a new store to the array automatically propagates it to all three material categories and the map.

Collection Points

Full list of all 6 Lima Este Tambo+ locations with addresses, districts, and GPS coordinates.

Recycling Map

Centro Verde municipal locations for glass, organic, electronic, and hazardous waste.

Build docs developers (and LLMs) love

Get started for freeTalk to us