Introduction & Product Vision
Relevant source files
The following files were used as context for generating this wiki page:
mdeapp is an AI-first, chat-centric discovery and ticketing platform designed specifically for the Medellín ecosystem. The platform integrates real-time AI assistance with map-based exploration to provide users with a "concierge" experience for finding rentals, events, nightlife, and local attractions. It leverages a modern stack including Next.js 16, Mastra, and Gemini 3.5 Flash, inheriting data from a legacy Supabase project containing over 100 tables.
Sources: README.md:1-5, README.md:16-25
Core Product Vision & Architecture
The vision for mdeapp is to transition from traditional search interfaces to an "Agentic UI" where discovery is driven by natural language conversations. The architecture is structured into specific layers that bridge frontend interactions with backend agentic logic.
Technical Stack Overview
| Layer | Technology |
|---|---|
| Frontend | Next.js 16 (App Router, React 19, Tailwind v4) |
| AI Shell | CopilotKit 1.55.2 |
| Bridge | @ag-ui/mastra |
| Agent Runtime | Mastra (beta) |
| Model | Gemini 3.5 Flash |
| Database | Supabase (Project: zkwcbyxiwklihegjhuql) |
| Maps | React Google Maps & Markerclusterer |
Sources: README.md:13-25, package.json:96-125
High-Level Data Flow
The following diagram illustrates how user queries move from the frontend through the AI bridge to the agent runtime and finally to the data sources.
The system uses CopilotRuntime and a MastraAgent bridge located in src/app/api/copilotkit/route.ts to manage these interactions.
Sources: README.md:28-33, README.md:16-20
Product Roadmap & Phases
The project follows a phased rollout plan aimed at achieving full feature parity and cutting over from the legacy mde system by Week 10.
- Phase 1, Week 1: Establish the
pingAgentto prove the wiring between CopilotKit, AG-UI, Mastra, and Gemini. - Week 3: Introduction of the "Roberto" host event flow, featuring Human-In-The-Loop (HITL) interactions via
renderAndWaitForResponse. - Week 5-6: Integration of Maps, rentals, and the "Camila" chat agent with read-only map state.
- Week 9: Payment integration via Stripe for ticket flows.
- Week 10: Final cutover from legacy mdeai.
Sources: README.md:7-9, README.md:43-50
Specialized Agent Ecosystem
mdeapp utilizes a multi-agent system where different agents are responsible for specific verticals of the Medellín experience. All product agents are standardized on the gemini-3.5-flash model.
Registered Agents
- pingAgent: System health and connectivity verification.
- routerAgent: Orchestrates queries to the correct specialized agent.
- rentalAgent: Handles short-term rental discovery and queries.
- conciergeAgent: General Medellín discovery and personalized recommendations.
- eventAgent: Specialized in finding and detailing local events.
- hostEventAgent: Manages the workflow for users to host their own events.
- evaluationAgent: Internal agent for assessing system performance.
Sources: src/tests/smoke.test.ts:25-35, src/tests/smoke.test.ts:55-65
Event Discovery Framework (F40)
A critical component of the product vision is the "Trusted Medellín Event Source Registry." The system enforces strict rules to ensure accuracy and reliability in event discovery.
Event Source Tiers
The registry categorizes sources into tiers to prioritize official and high-quality information:
- Official: Government and tourism boards (e.g., Medellín Travel Calendar, INDER).
- Ticketing: Established platforms (e.g., TuBoleta, La Tiquetera).
- Nightlife/Tech/Tourism/Community: Specialized niche sources.
Sources: src/lib/events/trusted-event-sources.ts:7-13, src/lib/events/trusted-event-sources.ts:31-55
Critical Discovery Rules
- No Invention: Agents must never invent events, venues, prices, or URLs.
- Tool Truth: Results from
search-eventstools are considered the only source of truth. - Deduplication: Future iterations must deduplicate events by title, date, and venue.
- Language: Phase 1 remains English-only for all AI-generated copy.
Sources: src/lib/events/trusted-event-sources.ts:57-65
Conclusion
mdeapp represents a shift toward intelligent, grounded discovery for the city of Medellín. By combining robust data from Supabase with the reasoning capabilities of Gemini 3.5 and the orchestration of Mastra, the platform provides a unified concierge interface that handles everything from casual coffee shop searches to complex event hosting workflows.