apiVersion: conventions/v1
version: 0.1.0
updated: "2026-06-29"
name: service_architecture
title: Service architecture (single API plane, peer services over HTTP)
scope: general
status: active
summary: One canonical API plane per platform; peer services (AI/ML/sync/screening) are consumed over HTTP/MCP, never vendored; authoring location ≠ runtime host. Consistent v0→v4.
appliesTo: ["@applications/*", "@projects/*"]
rules:
  - id: single_api_plane
    level: must
    text: One canonical backend API per platform; all surfaces (web/iOS/MCP/CLI) are clients of it. No second backend, no per-feature DB pools.
  - id: peers_over_http
    level: must
    text: "Peer services are consumed over HTTP/MCP, never vendored into another repo (e.g. @ai, @ml, mac-sync, mr-number, model-boss, prospector, people)."
  - id: ml_in_peers
    level: must
    text: ML/AI weights & inference live in peer apps; the platform holds orchestration only, never models/weights.
  - id: authoring_not_host
    level: must
    text: Code is authored in its repo (local/dev); named hosts are deploy targets only. Verify where something runs against INFRA.md before claiming it — never infer host roles from names.
  - id: own_db_per_service
    level: must
    text: Each service owns its own database/logical-DB + dedicated role; cross-service data access is HTTP, never a shared DB connection.
  - id: no_dev_planes
    level: should
    text: No standing dev DBs / dev APIs; engineering points at prod APIs, test DBs are ephemeral containers.