Developer Setup & Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides the necessary technical instructions to set up and run the mdeai application development environment. The platform is an AI-first discovery and ticketing system for Medellín, integrating Next.js, CopilotKit, Mastra, and Supabase.
Sources: README.md:3-5
Core Technology Stack
The application utilizes a modern, specialized stack for AI-agent interactions and map-based discovery.
| Layer | Technology |
|---|---|
| Frontend | Next.js 16 (App Router, React 19, Tailwind v4) |
| AI Shell | CopilotKit 1.55.2 |
| Agent Runtime | Mastra (beta) |
| LLM | Gemini 3.5 Flash |
| Database/Auth | Supabase |
| Maps | Google Maps JavaScript API |
Sources: README.md:15-22, package.json:81-112
Initial Environment Setup
1. Prerequisites and Installation
Ensure you have Node.js installed. Clone the repository and install dependencies using npm.
npm install
Sources: package.json:2-112
2. Environment Variables
The application requires several API keys and configuration strings to be defined in a .env.local file.
GOOGLE_GENERATIVE_AI_API_KEY: Required for Gemini 3.5 Flash.NEXT_PUBLIC_SUPABASE_URL: Supabase project URL.NEXT_PUBLIC_SUPABASE_ANON_KEY: Supabase anonymous key.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY: Google Maps JS API key.
Sources: README.md:19, package.json:21-22, src/components/maps/map-referer-help.tsx:29
3. Local Supabase Configuration
The project includes a Supabase configuration for local development.
| Parameter | Value |
|---|---|
| Project ID | mdeapp |
| API Port | 54321 |
| DB Port | 54322 |
| Studio Port | 54323 |
| Site URL | http://127.0.0.1:3000 |
Sources: supabase/config.toml:6-140
Running the Development Servers
The development environment requires running both the UI server and the Mastra agent runtime concurrently.
# Run both UI and Agent servers
npm run dev
# Run UI separately (Next.js)
npm run dev:ui
# Run Agent separately (Mastra)
npm run dev:agent
The UI server defaults to port 3001 and the Agent server to port 4111.
Sources: package.json:6-9, e2e/README.md:15
Application Architecture Flow
The following diagram illustrates how the local development components interact during a user session.
The application uses a bridge via src/app/api/copilotkit/route.ts to connect the CopilotRuntime with the Mastra Agent.
Sources: README.md:27-29, package.json:6-9
Mastra Workspace & Skills
Mastra agents are configured within a read-only workspace environment. This workspace is anchored to the package root and includes specific "governance skills."
- Workspace Path: Defaults to
join(packageRoot, "workspace")or theMDEAPP_WORKSPACEenvironment variable. - Security: Mutation tools (Write, Edit, Delete, Mkdir) are explicitly disabled in the workspace configuration.
Sources: src/mastra/workspaces.ts:11-23
Map Authentication Setup
To use the map features, the Google Maps API key must be restricted correctly in the Google Cloud Console (GCP).
Required HTTP Referrers
The following referrers must be allowed for local development:
http://localhost:3001/*http://localhost:3000/*http://127.0.0.1:3001/*http://127.0.0.1:3000/*
Sources: src/components/maps/map-referer-help.tsx:7-12
Testing and Verification
The project includes a robust suite of verification scripts and E2E tests.
Verification Scripts
Developers should run these scripts to verify environment health:
npm run verify:supabase: Checks Supabase environment variables.npm run verify:maps: Validates Google Maps API configuration.npm run check:mastra: Verifies Mastra agent registration.
Sources: package.json:16-17, package.json:34
E2E Testing with Playwright
E2E tests are organized by "screens" and functional verticals.
# Run all E2E tests
npm run test:e2e
# Run mobile-specific tests
npm run test:e2e:mobile
# Run screen-specific tests
npm run test:e2e:screens
Sources: package.json:37-43
Summary
The mdeai developer setup leverages a concurrent server model (Next.js + Mastra) and strict environment verification. By configuring local Supabase instances, restricting Google Maps referrers to the local dev ports (3000/3001), and utilizing the built-in verification scripts, developers can ensure the AI-agent and map-first discovery features function correctly before deployment.