Skip to content

Home

Jump to bottom
DCplatforms edited this page Jan 24, 2026 · 3 revisions

MiGrid — Central Service Routes & API Index

This wiki page centralizes the HTTP routes discovered across the MiGrid monorepo (L1 → L10 services). It is intended as an operational reference for developers and integrators. Where routes were discovered in service source files they are listed concretely. Where the service appears to be event-driven or missing an HTTP surface, placeholders are included with notes to confirm implementation details.

Sources:

  • services/*/index.js (repo scan)
  • README.md, DEPLOYMENT.md, docker-compose.yml
  • docs/api-specs/* (auto-generated OpenAPI stubs)

Caveat: repository code search is limited; consider this page a draft. For full coverage, run an additional repo code search for express app/router files and nested router modules.

Quick start (local)

Assumes services run with docker-compose in repo root:

git clone https://github.com/dcplatforms/Migrid.git
cd Migrid
docker-compose up --build -d
# check health for all services
for port in 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010; do
  echo "http://localhost:$port/health"
  curl -s http://localhost:$port/health | jq || true
done

Service matrix (ports & short purpose)

  • L1 — Physics Engine (port 3001) — session auditing / DB listener
  • L2 — Grid Signal (port 3002) — OpenADR 3.0 VEN (utility DR and price signals)
  • L3 — VPP Aggregator (port 3003) — fleet capacity aggregation
  • L4 — Market Gateway (port 3004) — LMP & market integration (CAISO/PJM/ERCOT)
  • L5 — Driver Experience API (port 3005) — auth, mobile backend (JWT)
  • L6 — Engagement Engine (port 3006) — leaderboards, achievements
  • L7 — Device Gateway (ports 3007 & 9220) — OCPP bridge / charger control (HTTP + WebSocket)
  • L8 — Energy Manager (port 3008) — Dynamic Load Management (DLM)
  • L9 — Commerce Engine (port 3009) — billing / invoices / payments
  • L10 — Token Engine (port 3010) — rewards pipeline & blockchain bridge

Discovered service routes (summaries + examples)

Note: base URL is http://localhost:{port}

L3 — VPP Aggregator (http://localhost:3003)

Found in: services/03-vpp-aggregator/index.js

  • GET /health
    • Response: { service, version, status, layer }
  • GET /capacity/available
  • POST /resources/register
    • Body: { vehicle_id, battery_capacity_kwh, v2g_enabled }
    • Validation: battery_capacity_kwh >= 50
    • Example: curl -X POST http://localhost:3003/resources/register
      -H "Content-Type: application/json"
      -d '{"vehicle_id":"veh-123","battery_capacity_kwh":75,"v2g_enabled":true}'

L4 — Market Gateway (http://localhost:3004)

Found in: services/04-market-gateway/index.js

  • GET /health
  • GET /markets
    • Lists available markets (CAISO, PJM, etc.)
  • GET /markets/{iso}/prices
  • POST /bids/submit
    • Body: { iso, market_type, quantity_kw, price_per_mwh, delivery_hour }
    • Validation: quantity_kw >= 100
    • Example: curl -X POST http://localhost:3004/bids/submit -H "Content-Type: application/json" -d '{"iso":"CAISO","market_type":"day-ahead","quantity_kw":150,"price_per_mwh":45.5,"delivery_hour":"2026-01-25T14:00:00Z"}'

L5 — Driver Experience API (http://localhost:3005)

Found in: services/05-driver-experience-api/index.js

  • GET /health
  • POST /auth/register
    • Body: { email, password, first_name, last_name, fleet_id }
    • Response: created driver object (201)
  • POST /auth/login
    • Body: { email, password }
    • Response: { token, driver }
    • JWT auth middleware present in service; protected routes will require Authorization: Bearer

Example:

curl -X POST http://localhost:3005/auth/login -H "Content-Type: application/json" \
-d '{"email":"alice@demo.com","password":"demo123"}'

Auth note: middleware verifies JWT using JWT_SECRET in env. Use Authorization: Bearer <token> for protected routes.

L6 — Engagement Engine (http://localhost:3006)

Found in: services/06-engagement-engine/index.js

  • GET /health
  • GET /leaderboard?fleet_id=&limit=
    • Returns leaderboard (with optional fleet filter, limit)
  • GET /leaderboard/driver/{driver_id}
    • Returns driver rank or { rank: null, message: ... }
  • GET /achievements
    • Returns list of achievement templates
  • GET /achievements/driver/{driver_id}
    • Lists achievements earned by driver
  • POST /achievements/award
    • Body: { driver_id, achievement_id }
    • Validates duplicate awards, updates leaderboard, recalculates ranks
  • GET /challenges/active
    • (demo/hardcoded challenges)

Example: curl http://localhost:3006/leaderboard

L8 — Energy Manager (http://localhost:3008)

Found in: services/08-energy-manager/index.js

  • GET /health
  • GET /load/current
    • Returns building_load_kw, ev_load_kw, total_load_kw, grid_limit_kw, available_kw, utilization_percent
  • GET /load/history?hours={n}
    • Returns historical load measurements
  • GET /dlm/available-capacity
    • Returns available_for_ev_kw, active_chargers, per_charger_limit_kw
  • POST /dlm/apply
    • Applies DLM policy, distributes available power across active sessions
    • Returns allocations with charger_id, vehicle_id, allocated_power_kw

Example: curl http://localhost:3008/dlm/available-capacity curl -X POST http://localhost:3008/dlm/apply

L1 — Physics Engine (http://localhost:3001)

Found in: services/01-physics-engine/index.js

  • Implementation: DB listener (pg LISTEN new_charging_session). Primary function is audit/verification of sessions.
  • HTTP surface: none discovered in index.js. Placeholder: consider adding GET /health if needed.

L2 — Grid Signal (http://localhost:3002)

Found: Dockerfile and docs references indicate OpenADR VEN support (OpenADR 3.0)

  • Expected flows: OpenADR callbacks / VEN interfaces; specific HTTP routes not found in repo scan.
  • Placeholder route suggestion: POST /openadr/events (confirm with service source)

L7 — Device Gateway (http://localhost:3007, WS 9220)

Notes:

  • Dockerfile present and ports exposed (3007 & 9220).
  • Purpose: OCPP 2.0.1 charger interaction (HTTP + WebSocket). Route modules not found in top-level scan.
  • Suggested REST endpoints (placeholders): GET /health, GET /chargers, GET /chargers/{id}/status, POST /chargers/{id}/command
  • OCPP operations will primarily be over WebSocket (port 9220). Document OCPP WebSocket URI and sample client flows.

L9 — Commerce Engine (http://localhost:3009)

Notes:

  • Container referenced in docker-compose. No index.js found in top-level code search.
  • Expected endpoints (placeholders): GET /health, GET /invoices, GET /invoices/{id}, POST /payments/charge
  • Integration: Stripe, OCPI CDRs. Fill exact routes once service code is available.

L10 — Token Engine (http://localhost:3010)

Found in: services/10-token-engine/index.js — primarily Kafka consumer + DB helpers.

  • Primary behavior: Kafka consumer that awards points, interacts with Open-Wallet.
  • No explicit HTTP server in index.js scan. Optional admin endpoints may exist or be added (e.g., GET /wallets/{driver_id}, GET /rewards/logs).
  • If HTTP surfaces are required for ops, add minimal GET /health and /wallets endpoints.

OpenAPI specs & per-service YAML (generated stubs)

Auto-generated stubs (place in repo docs/api-specs/):

  • docs/api-specs/01-physics-engine.yaml (placeholder)
  • docs/api-specs/02-grid-signal.yaml (placeholder)
  • docs/api-specs/03-vpp-aggregator.yaml
  • docs/api-specs/04-market-gateway.yaml
  • docs/api-specs/05-driver-experience.yaml
  • docs/api-specs/06-engagement-engine.yaml
  • docs/api-specs/07-device-gateway.yaml (placeholder)
  • docs/api-specs/08-energy-manager.yaml
  • docs/api-specs/09-commerce-engine.yaml (placeholder)
  • docs/api-specs/10-token-engine.yaml (minimal)

Recommendation:

  • Keep per-service specs close to their service (e.g., services/03-vpp-aggregator/openapi.yaml) OR continue with central docs/api-specs. Use Redoc/Swagger UI for interactive explorer from the docs site.

Authentication & security notes

  • Driver Experience (L5) uses JWT (jwt.verify middleware). Use Authorization: Bearer for protected routes.
  • Services talking to each other should be secured via mTLS in production (docs/roadmap suggests zero-trust).
  • Secrets: JWT_SECRET, DATABASE_URL, STRIPE_API_KEY, POLYGON_RPC_URL are configured in docker-compose / env.

Operational & contribution guidance

  • To add/modify documented routes:
    1. Update the service source (services/XX-*/index.js or router module)
    2. Update per-service OpenAPI YAML in docs/api-specs/ (or next to service)
    3. Update this wiki page with new/changed routes
    4. Add a docs PR including OpenAPI validation (e.g., swagger-cli validate) in CI
  • Consider a small script to auto-extract simple Express route patterns into the YAML stubs (useful for keeping docs in sync).

Caveats & next steps

  • This page is not a full authoritative contract. Some services are event-driven (Kafka/DB LISTEN) and do not expose HTTP endpoints.
  • Next steps:
    • Confirm placeholders for L1, L2, L7, L9, L10 by inspecting their service source files or asking maintainers to expose admin endpoints.
    • Add security schemes to OpenAPI (bearerAuth) and example tokens for dev.
    • Optionally generate a single merged openapi.yaml from the per-service files for a central API explorer.

Clone this wiki locally