MOCA — Mobility Coordination App

MOCA is a Next.js (App Router) application for on-demand mobility coordination, designed for "福富町" style use-cases. It features a Japanese-localized UI for both passengers and operators, a built-in HTTP API, and geospatial routing powered by Supabase and OSRM.

This README is your technical guide—covering project structure, setup, API, integrations, and design notes to help you get productive fast.

---

Table of Contents

• Overview
• Quick Start
• Environment Variables
• Architecture
• Key Files & Directories
• API Design
• Data Flow & Integrations
• Types & Validation
• UI Structure
• Migrations & Database
• Testing & Linting
• Deployment
• Troubleshooting
• Contributing

---

Overview

• Framework: Next.js (App Router), React 19, TypeScript
• UI:
  • Passenger booking (app/page.tsx)
  • Operator dashboard (app/operator)
• API: Next.js route handlers (app/api/*) using Supabase
• Geospatial: OSRM integration with fallback dummy routing

Quick Start

1. Install dependencies (choose one):

   npm install
   # or
   pnpm install
   # or
   yarn

2. Configure environment: Create .env.local (see Environment Variables), then run:

   npm run dev
   # or
   pnpm dev

3. Scripts: Available in package.json:

   • dev — Start dev server
   • build — Production build
   • start — Run built app
   • types — Type-check

Environment Variables

Create .env.local (do not commit):

NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

Missing variables will cause errors in lib/supabase.ts.

Architecture

• Frontend: React pages/components call Next.js API routes (app/api/*)
• Backend: API routes use Supabase client (lib/supabase.ts)
• Routing: lib/osrm.ts handles OSRM HTTP API calls, with fallback to dummy generator
• Types: Defined in /types/*, validated with Zod
• UI: Components in /components use strict typing

Key Files & Directories

• App Entrypoints:
  • app/page.tsx — Passenger booking
  • app/operator/page.tsx — Operator dashboard
  • app/layout.tsx — Global layout, font, footer
• API Handlers:
  • app/api/points/route.ts — List/create points
  • app/api/points/[id]/route.ts — Single point CRUD
  • app/api/routes/route.ts — Routes list/create
  • app/api/reservations/*, app/api/vehicles/*, app/api/demand-predictions/* — More endpoints
• Lib:
  • lib/supabase.ts — Supabase client
  • lib/api-helpers.ts — Response helpers, Zod formatting, error translation
  • lib/osrm.ts — OSRM integration & fallback
• Types:
  • types/ — API/component types, Zod schemas
• Components:
  • components/Booking.tsx, FukutomiMap.tsx, RouteList.tsx, PointList.tsx, etc.
• Docs:
  • docs/API.md — API details & examples
  • docs/migrations/ — SQL migrations

API Design

All API routes return JSON in a consistent format:

• Success:

  { "success": true, "data": { ... }, "message": "optional" }

• Error:

  {
    "success": false,
    "error": "message",
    "details": [{ "field": "name", "message": "..." }]
  }

See docs/API.md for full endpoint specs.

Data Flow & Integrations

• Supabase: Typed client in lib/supabase.ts. Errors mapped to user-friendly messages via handleSupabaseError in lib/api-helpers.ts.
• OSRM:
  • generateRouteWithOSRM(points, startTime) — Real routing
  • generateDummyRouteData(points, startTime) — Fallback
  • getOrGenerateRouteData(...) — Tries OSRM, falls back if needed

OSRM is called via the public router.project-osrm.org URL. For production, consider hosting your own OSRM instance or using a paid routing API for stability.

Types & Validation

• Zod schemas for all API payloads (see types/api.points.types.ts)
• Helpers in lib/api-helpers.ts:
  • formatZodErrors() — Normalize validation errors
  • validateBody(request, schema) — Safe JSON + schema check
  • parseQueryParams(request) — Typed query parsing
  • handleSupabaseError(error) — DB error translation
• Type hints for Supabase DB in types/supabase.types.ts

UI Structure

• Map: components/FukutomiMap.tsx (Leaflet, client-only)
• Booking: components/Booking.tsx (map + route list + reservation)
• Operator: CRUD for points/routes, live map updates
• Primitives: Header.tsx, Sidebar.tsx, Card.tsx, Dialog.tsx, etc.

The operator page (app/operator/page.tsx) demonstrates the full CRUD flow for points, including live map updates.

Migrations & Database

• SQL migrations in docs/migrations/
• Schema changes: update migrations and Zod types together
• Use Supabase panel or migration runner to apply SQL

Testing & Linting

• TypeScript strict mode
• Type-check:

  npm run types