# ADR: Sankofa IT control-plane API placement

**Status:** Accepted (2026-04-09)  
**Context:** [SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md](./SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md)  
**Decision:** Where the IT BFF / read API lives relative to `dbis_core` and deployment topology.

## Decision

1. **Phase 0–1 (current):** The **read-only HTTP surface** stays in this **proxmox** repo as [`services/sankofa-it-read-api/server.py`](../../services/sankofa-it-read-api/server.py), deployed to a **seed Proxmox node** under `/opt/proxmox` (see [`bootstrap-sankofa-it-read-api-lan.sh`](../../scripts/deployment/bootstrap-sankofa-it-read-api-lan.sh)). It serves LAN/VLAN 11 only (plus optional NPM internal host). **No coupling to `dbis_core` runtime.**

2. **Phase 2+ (full BFF):** Add a **dedicated small service** (same repo or new `sankofa-it-api` repo) on a **dedicated CT** with **Postgres** for snapshots, drift history, port-map CRUD, and audit log. **Still not** embedded in the `dbis_core` monolith, to avoid shipping Proxmox/UniFi secrets with the app server and to allow independent deploy/rollback.

3. **Marketplace / billing linkage:** Native infra SKUs and Stripe (or other) subscriptions are **linked** from the IT DB to **`dbis_core`** catalog rows via **`external_sku_id`** / subscription id (see [`config/it-operations/entitlements-schema.sql`](../../config/it-operations/entitlements-schema.sql)). **`dbis_core` remains the commerce/API source** for partner IRU patterns; the IT controller stores **entitlements and metering**, not a second unrelated product catalog.

## Consequences

- Operators clone **proxmox** for IT scripts, workflows, and read API; portal (`Sankofa/portal`) calls **`IT_READ_API_URL`** on LAN.
- Future OIDC validation and Postgres move **replace or front** the read API without changing portal route contracts (`/v1/inventory/*`, `/v1/summary`).
- `dbis_core` PRs do not need to land for every IT collector change.

## Alternatives considered

| Option | Rejected because |
|--------|------------------|
| BFF inside **dbis_core** | Couples infra secrets and deploy cadence to Phoenix/API releases; larger blast radius. |
| **Only** markdown/git as UI | Violates live-first rule; no `collected_at` or drift alerts. |
| Public BFF without auth | Violates spec; Proxmox data must not be world-readable. |