dbd517b279
- Update dbis_core, cross-chain-pmm-lps, explorer-monorepo, metamask-integration, pr-workspace/chains - Omit embedded publish git dirs and empty placeholders from index Made-with: Cursor
28 lines
2.3 KiB
Markdown
28 lines
2.3 KiB
Markdown
# 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. |
|