__  __              _          _
|  \/  |  __ _  _ __| |    __ _| |__
| |\/| | / _` || '_ \ |   / _` | '_ \
| |  | || (_| || |_) | |_| (_| | |_) |
|_|  |_| \__,_|| .__/|_____\__,_|_.__/
                |_|

MapLab is a version control and community platform built specifically for ECU tuning directly in your browser. It lets tuners upload, track, and compare binary tune files (BIN, XDF, A2L, DAMOS) across branches and commits — similar to Git, but purpose-built for ECU workflows.

Beyond version control, MapLab is a community hub: tuners can publish their projects publicly, explore and fork other people's tunes, leave comments, and collaborate on calibrations. An integrated map editor lets you view and edit ECU maps directly in the browser, with a 3D visualizer and an AI-powered explanation panel for individual map cells.

The platform is designed for professional tuners and enthusiasts alike — from a single-car hobbyist tracking changes to their own tune, to a shop managing calibrations across a fleet of vehicles.

maplab/
├── apps/
│   └── web/               # Next.js 15 app (App Router)
├── packages/
│   ├── db/                # Prisma client + schema (PostgreSQL via Supabase)
│   ├── ui/                # Shared component library (shadcn/ui)
│   ├── types/             # Shared TypeScript types
│   ├── ecu-parser/        # ECU parser core (Rust)
│   └── ecu-parser-wasm/   # WASM build output + JS bindings
└── services/
    └── ecu-engine/        # ECU parsing API (Python FastAPI)

External services required: Supabase (auth + database), Cloudflare R2 (file storage), Anthropic API (AI features, optional).

The app ships a pre-built WASM fallback, so Rust is not required to run MapLab locally.

1. Copy the example env file:

   cp .env.example apps/web/.env.local

2. Fill in the required values in apps/web/.env.local:

   # Supabase — create a project at https://supabase.com
   NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
   SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
   
   # Database — from your Supabase project settings → Database → Connection string
   DATABASE_URL=postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres?pgbouncer=true
   DIRECT_URL=postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres
   
   # Cloudflare R2 — create a bucket at https://dash.cloudflare.com
   R2_ACCOUNT_ID=your-account-id
   R2_ACCESS_KEY_ID=your-access-key
   R2_SECRET_ACCESS_KEY=your-secret-key
   R2_BUCKET_NAME=maplab-files
   R2_PUBLIC_URL=https://files.maplab.app
   
   # ECU Parser (set automatically in Docker, leave as-is for hybrid mode)
   ECU_PARSER_URL=http://localhost:8000
   ECU_PARSER_SECRET=your-internal-secret
   
   # Anthropic (optional — AI features only)
   ANTHROPIC_API_KEY=sk-ant-...
   
   # Feature flags (optional)
   NEXT_PUBLIC_AI_ENABLED=false
   NEXT_PUBLIC_3D_ENABLED=false
   NEXT_PUBLIC_MARKETPLACE_ENABLED=false

3. Push the database schema:

   pnpm --filter @maplab/db db:push

The ecu-engine runs in Docker; the Next.js app runs natively for fast hot-reload.

./dev.sh

What it does:

• Starts ecu-engine via Docker Compose and waits for it to be healthy
• Installs JS dependencies (pnpm install) if needed
• Starts the Next.js dev server on http://localhost:3000
• Stops Docker services automatically on Ctrl+C

All services run inside Docker Compose. Slower hot-reload but no local Node.js required.

./dev.sh --docker

Or directly via Docker Compose:

docker compose --profile full up --build

Services:

# ECU engine only (detached)
docker compose up -d ecu-engine

# Next.js only (requires ecu-engine running)
pnpm install
pnpm --filter @maplab/web dev

# Apply schema changes (development)
pnpm --filter @maplab/db db:push

# Run migrations
pnpm --filter @maplab/db db:migrate

# Open Prisma Studio
pnpm --filter @maplab/db db:studio

# Seed with test data
pnpm --filter @maplab/db db:seed

Only needed if you modify the Rust parser in packages/ecu-parser/.

pnpm wasm:build

Output is written to packages/ecu-parser-wasm/wasm/ and copied to apps/web/public/wasm/.

# Type-check the entire monorepo
pnpm typecheck

# Lint
pnpm lint

# Format all files
pnpm format

# Build all packages
pnpm build

# Clean all build artifacts and node_modules
pnpm clean