Environment & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Environment and configuration management in mdeapp facilitates a multi-layered architecture involving Next.js for the frontend, Supabase for data persistence and authentication, and Mastra for AI agent orchestration. The project relies on environment variables to manage sensitive API keys for Gemini AI and Google Maps, alongside local configuration files for database services and development tooling.
Sources: README.md:1-25, package.json:1-80
Core Infrastructure Configuration
The application architecture is defined by several integrated layers, each requiring specific configuration to maintain the "AI-first, chat-first, map-first" platform requirements.
System Architecture Overview
This diagram illustrates the high-level flow where the Next.js frontend interacts with Mastra for agent logic and Supabase for data.
Sources: README.md:12-25
Key Technology Stack
| Layer | Technology | Configuration / Version |
|---|---|---|
| Frontend Framework | Next.js | version 16.2.6 (App Router, Turbopack) |
| AI Framework | CopilotKit | version 1.55.2 (pinned) |
| Agent Runtime | Mastra | beta (agents in src/mastra/agents/) |
| Language Model | Gemini 3.5 Flash | via @ai-sdk/google |
| Database/Auth | Supabase | Project zkwcbyxiwklihegjhuql |
| Maps | Google Maps | @vis.gl/react-google-maps |
Sources: README.md:12-25, package.json:80-110
Environment Variables
The project utilizes .env.local for local development. Configuration is split between public variables (prefixed with NEXT_PUBLIC_) and server-side secrets.
Required Environment Variables
| Variable | Scope | Description |
|---|---|---|
GOOGLE_GENERATIVE_AI_API_KEY | Server | API key for Gemini 3.5 Flash model access. |
SUPABASE_URL | Server | The endpoint for the Supabase project. |
SUPABASE_ANON_KEY | Server | Public anonymous key for client-side Supabase interactions. |
NEXT_PUBLIC_SUPABASE_URL | Client | Mirrored Supabase URL for client-side SDK initialization. |
SUPABASE_SERVICE_ROLE_KEY | Server | Admin key used in testing and server-side privileged operations. |
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY | Client | API key for rendering Google Maps and Place components. |
Sources: README.md:21, src/mastra/tools/search-attractions.ts:63-65, e2e/screens/SCREEN-013-itinerary.spec.ts:74-85
Supabase Local Configuration
Supabase is configured via supabase/config.toml for local development environments, defining ports, schemas, and security settings.
API and Database Settings
The local Supabase instance exposes the public and graphql_public schemas on port 54321. The database itself runs on port 54322 using PostgreSQL major version 17.
project_id = "mdeapp"
[api]
port = 54321
schemas = ["public", "graphql_public"]
[db]
port = 54322
major_version = 17
[auth]
site_url = "http://127.0.0.1:3000"
jwt_expiry = 3600
Sources: supabase/config.toml:5-15, supabase/config.toml:25-35, supabase/config.toml:130-140
Google Maps Configuration & Troubleshooting
The project requires specific Google Cloud Platform (GCP) configurations to enable the Map-first UI. The MapRefererHelp component documents the necessary browser restrictions and API activations required for the NEXT_PUBLIC_GOOGLE_MAPS_API_KEY.
Referrer Allow-list
For local development, the following referrers must be permitted in the GCP Console:
http://localhost:3001/*http://localhost:3000/*http://127.0.0.1:3001/*http://127.0.0.1:3000/*
Required APIs
The application logic assumes the following services are enabled:
- Maps JavaScript API: For UI rendering.
- Places API: Specifically for
google_place_idlookups and enrichment. - Billing: GCP billing must be active to avoid
BillingNotEnabledMapError.
Sources: src/components/maps/map-referer-help.tsx:7-45, src/mastra/tools/search-attractions.ts:40-45
Development & Test Configuration
Development workflows are managed through package.json scripts, orchestrating both the UI and AI agent runtimes simultaneously.
Execution Scripts
The standard development command npm run dev uses concurrently to launch the Next.js UI on port 3001 and the Mastra agent server on port 4111.
# Start UI and Agent runtime
npm run dev
# Specific sub-commands
"dev:agent": "PORT=4111 mastra dev"
"dev:ui": "next dev --webpack -p 3001"
Sources: package.json:6-10
Testing Environment Injection
End-to-end tests (Playwright) and integration tests (Vitest) include helpers to load environment variables from .env.local manually when running outside of the standard Next.js environment.
function loadEnvLocalForE2E() {
const envPath = path.resolve(process.cwd(), ".env.local");
if (!fs.existsSync(envPath)) return;
const text = fs.readFileSync(envPath, "utf8");
// ... logic to parse and assign to process.env
}
Sources: e2e/screens/SCREEN-013-itinerary.spec.ts:114-130
Conclusion
Environment and configuration in mdeapp are strictly decoupled between the frontend UI (Next.js), the agentic runtime (Mastra), and the data backend (Supabase). Proper initialization requires a coordinated setup of both local files (config.toml, .env.local) and cloud service configurations (GCP Referrers, Supabase RLS) to ensure the integrated AI-Concierge functions correctly across different development and testing tiers.
Summary of Significance:
- Port 3001: Default UI development port.
- Port 4111: Default Mastra agent port.
- Gemini 3.5 Flash: Default model for all agents.
Sources: package.json:5-15, README.md:12-25