Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The mdeai application is an "AI-first, chat-first, map-first" discovery and ticketing platform specifically designed for Medellín. It leverages a modern stack centered around Next.js 16, Supabase for data and authentication, and a sophisticated AI agent runtime using Mastra and CopilotKit. The system is designed to facilitate discovery of rentals, events, and nightlife while providing a seamless bridge between natural language chat and interactive map-based exploration.
Sources: README.md:3-5, src/app/layout.tsx:21-23
Technical Stack and Layers
The project is structured into distinct layers ranging from the frontend user interface to the backend agent runtime and data persistence.
| Layer | Technology |
|---|---|
| Frontend | Next.js 16 (App Router), React 19, Tailwind v4, Lucide React |
| AI Shell | CopilotKit 1.55.2 |
| Agent Runtime | Mastra (beta) |
| Model | Gemini 3.5 Flash via @ai-sdk/google |
| Data / Auth | Supabase (PostgreSQL 17, RLS-tight) |
| Maps | @vis.gl/react-google-maps + @googlemaps/js-markerclusterer |
| Payments | Stripe (planned for W9+) |
Sources: README.md:10-18, package.json:115-140, supabase/config.toml:39
Core System Components
1. AI Agent Orchestration (Mastra)
The application utilizes Mastra as the agent runtime. Agents are defined within src/mastra/agents/ and registered in a centralized Mastra instance. These agents are specialized for different domains such as rentals, events, and concierge services. All product-facing agents are standardized on the Gemini 3.5 Flash model.
Key agents registered in the system include:
pingAgent: Demonstrates basic wiring.routerAgent: Orchestrates requests between specialized agents.rentalAgent: Handles property and short-term rental discovery.eventAgent: Manages discovery of local events and nightlife.hostEventAgent: Facilitates a human-in-the-loop (HITL) flow for users to host events.conciergeAgent: General purpose assistance.
Sources: README.md:31-36, src/tests/smoke.test.ts:16-30, src/tests/smoke.test.ts:54-65
2. CopilotKit Integration
CopilotKit serves as the "AI chat shell" and the bridge between the frontend UI and the Mastra agent runtime. It is integrated via a runtime route and a provider in the root layout.
- Frontend Provider: The
<MdeCopilotKitProvider>wraps the application to enable AI features throughout the component tree. - Backend Bridge: The API route at
src/app/api/copilotkit/route.tsacts as theCopilotRuntimeandMastraAgentbridge.
Sources: src/app/layout.tsx:55-57, README.md:31-33, package.json:121-123
3. Data and Persistence (Supabase)
The system reuses a Supabase project containing 122 tables with strict Row Level Security (RLS). The infrastructure supports local development through the Supabase CLI, using PostgreSQL version 17.
- API Port: 54321
- DB Port: 54322
- Auth: Email-based signup and magic links are enabled, with session persistence managed through custom middleware and client/server-side libraries.
Sources: README.md:16, supabase/config.toml:13-39, src/tests/smoke.test.ts:79-88
System Flow and Data Lifecycle
The following diagram illustrates the flow from a user query in the Next.js frontend to the AI agent processing and eventual data retrieval from Supabase.
The diagram shows the sequence from user input through the CopilotKit bridge to the Mastra runtime, which coordinates with Google Gemini and Supabase to return grounded results.
Sources: README.md:28-40, src/app/layout.tsx:52-60, src/tests/smoke.test.ts:16-30
Project Structure
The codebase is organized to separate UI components, AI logic, and infrastructure configuration.
| Directory | Description |
|---|---|
src/app/ | Next.js App Router pages, layouts, and API routes. |
src/components/ | Reusable UI components (shadcn/ui base). |
src/mastra/ | Mastra runtime configuration, agent definitions, and tools. |
src/mastra/skills/ | Modular workspace skills (e.g., mde-rental-quality, mde-safe-actions). |
src/lib/ | Shared utilities, types, and database clients. |
supabase/ | Local Supabase configuration, migrations, and seeds. |
e2e/ | Playwright end-to-end test suites for various screens and flows. |
Sources: README.md:28-40, src/mastra/workspaces.test.ts:10-16, package.json:13-40
Workspace Skills
The Mastra workspace is configured with a "read-only" architecture for local filesystem operations to ensure security. Mutation tools like WRITE_FILE and DELETE are explicitly disabled in the workspace configuration. The system utilizes specific skill directories for modular logic:
mde-prompt-qamde-rental-qualitymde-safe-actionsmde-event-reviewmde-followup-logic
Sources: src/mastra/workspaces.test.ts:10-16, src/mastra/workspaces.test.ts:33-43
Conclusion
The mdeapp architecture represents a sophisticated integration of modern AI agent frameworks (Mastra) and developer-focused AI SDKs (CopilotKit). By layering these over a robust Next.js frontend and a well-established Supabase backend, the platform provides a high-performance environment for discovery in Medellín, emphasizing responsiveness through Gemini 3.5 Flash and accurate spatial grounding via Google Maps.