Next.js API Routes
Relevant source files
The following files were used as context for generating this wiki page:
The mdeapp project utilizes Next.js App Router API Routes to provide a backend infrastructure for AI agent orchestration, external data grounding, and application-specific services. These routes act as a bridge between the frontend UI, the Mastra agent runtime, and external services like Google Places and Supabase.
The primary role of the API layer is to facilitate "chat-first" and "map-first" discovery by exposing endpoints that the AI concierge and the frontend components can consume to retrieve verified information about Medellín.
Core Architecture and Data Flow
The API routes are primarily implemented as Route Handlers within the src/app/api directory. They leverage the nodejs runtime and are often configured for dynamic execution to ensure fresh data retrieval.
AI Runtime Integration
The project uses CopilotKit and Mastra to handle AI interactions. A critical route is /api/copilotkit, which serves as the bridge between the CopilotRuntime and Mastra agents.
The flow of AI-driven requests through the CopilotKit and Mastra integration.
Sources: README.md:25-30, src/app/api/copilotkit/route.ts
Grounded Search Logic
The /api/grounded/search route provides a "fast path" for location-based searches without requiring the full concierge agent overhead. It validates input using zod and executes the searchGroundedPlacesTool.
Sources: src/app/api/grounded/search/route.ts:18-40
Endpoint Specifications
1. Grounded Search
Path: /api/grounded/search
Method: POST
Description: Executes a search for Google-verified places (cafes, nightlife, etc.) within Medellín.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | The search terms (min 1 char). |
neighborhood | string | No | Specific neighborhood to filter by. |
limit | number | No | Results limit (1-10, default 5). |
intent | enum | No | cafe, nightlife, or general. |
Sources: src/app/api/grounded/search/route.ts:9-16
2. CopilotKit Runtime
Path: /api/copilotkit
Method: POST
Description: Entry point for the AI concierge. It connects the frontend chat interface to the Mastra-managed agents like pingAgent or hostEventAgent.
Sources: README.md:25-30
Implementation Details
Validation and Security
API routes utilize zod for strict schema validation of request bodies. This ensures that only well-formatted data reaches the underlying tools and workflows.
const bodySchema = z.object({
query: z.string().min(1),
neighborhood: z.string().optional(),
limit: z.number().int().min(1).max(10).optional().default(5),
intent: z.enum(["cafe", "nightlife", "general"]).optional(),
});
Sources: src/app/api/grounded/search/route.ts:9-16
Workflow Integration
The API routes often trigger Mastra workflows, such as the concierge-routing-workflow. This workflow performs deterministic intent classification (e.g., rental_search, event_discovery) before dispatching the request to the appropriate data source.
Sequence of internal workflow steps triggered by API interactions.
Sources: src/mastra/workflows/concierge-routing-workflow.ts:168-230
Server-Side Data Loading
While not always strictly "API Routes," the project uses Next.js Server Components and the Supabase Server Client to load data directly in pages, which complements the API layer. For example, trip details are loaded using loadTripWorkspace after verifying the user session.
Sources: src/app/trips/[id]/page.tsx:14-35
Summary
Next.js API Routes in mdeapp serve as the functional backbone for the Medellín discovery platform. By combining zod validation, Mastra agent tools, and CopilotKit orchestration, the system provides a robust interface for both automated AI chat interactions and direct data querying for venues and events.