# Platform Architecture Open Decisions v1

Status: draft for review
Owner: Platform Architecture
Last updated: 2026-06-02

## Purpose

Track open decisions that span multiple architecture docs. Individual docs may
keep local open-decision sections, but duplicated or cross-cutting decisions
should point here so ownership and sequencing stay clear.

## Decisions

| ID | Decision | Affected docs | Severity | Blocked on | Owner | Resolved |
|---|---|---|---|---|---|---|
| OD-001 | Which shared-service registries become schema tables first versus seeded config | PSSM, Unified IAM/Billing, Token Factory Gateway | High | OD-002 | Platform Architecture | Partially resolved for current PSSM runtime adoption: registries are seed-backed through `packages/platform/registry`; schema-backed production registry storage remains open for future Token Factory readiness / production registry migration. See `platform-foundation/Platform_Registry_Contract_v1.md`, `platform-foundation/Platform_Shared_Services_L2_Readiness_Matrix_v1.md`, and `platform-foundation/Platform_Shared_Services_L3_Decision_Gate_v1.md`. |
| OD-002 | Exact registry version snapshot schema for scopes, usage units, audit actions, notifications, and products | PSSM, Unified IAM/Billing | High | - | IAM / Billing | Partially resolved for current runtime paths: active registry IDs/versions are validated and recorded where needed; irreversible registry snapshot schema remains open before production registry-storage migration or future Token Factory activation. See `platform-foundation/Platform_Shared_Services_L2_Readiness_Matrix_v1.md`. |
| OD-003 | Keycloak role placement: realm roles, client roles, or platform-only role bindings projected into tokens | Unified IAM/Billing | Medium | - | IAM | |
| OD-004 | Per-key budget/rate-limit enforcement split across Pomerium `api_bearer`, Token Factory gateway, and billing policy | Unified IAM/Billing, API Gateway, Token Factory Gateway | High | OD-005 | IAM / Token Factory | Readiness packet drafted; pending final Token Factory ADR when that product becomes active. See `token-factory/Token_Factory_Readiness_Decision_Packet_v1.md`. |
| OD-005 | Kong vs Tyk vs Envoy-direct for Token Factory gateway | API Gateway, Token Factory Gateway | High | - | Token Factory | Readiness packet recommends future Envoy-direct spike with Kong/Tyk fallback criteria; pending spike/ADR when Token Factory becomes active. See `token-factory/Token_Factory_Readiness_Decision_Packet_v1.md`. |
| OD-006 | Authoritative token counting source and reconciliation path | Token Factory Gateway, Unified IAM/Billing | High | OD-005 | Token Factory / Billing | Readiness packet recommends gateway-side accepted usage with backend reconciliation for v1; pending final ADR when Token Factory becomes active. See `token-factory/Token_Factory_Readiness_Decision_Packet_v1.md`. |
| OD-007 | Cross-product quota composition and customer-facing quota UX | Unified IAM/Billing, PSSM Gap Register | Medium | - | Product / IAM | |
| OD-008 | First Status/Ops read model: admin-only or customer-facing from day one | PSSM, Cert-Manager, Node Agent docs | High | - | Ops | Resolved for first implementation: start with operator/security/release evidence and platform readiness read models; customer-safe exposure remains a later surface decision. See `platform-foundation/Platform_Evidence_Status_Slice_v1.md`, `platform-foundation/Platform_Evidence_Status_Frontend_Contract_v1.md`, and `platform-foundation/Platform_Shared_Services_Completion_Roadmap_v1.md`. |
| OD-009 | cert-manager DNS-01 solver per edge profile, including airgapped/private challenge path | Cert-Manager Integration | High | - | Ops / Security | |
| OD-010 | cert-manager issuer policy: ClusterIssuer defaults and namespaced delegation rules | Cert-Manager Integration | Medium | - | Ops / Security | |
| OD-011 | Host certificate delivery pattern, if any, from cert-manager-managed material | Cert-Manager, Node Agent Cert Lifecycle | Medium | - | PKI / Node Agent | |
| OD-012 | OLTP/OLAP boundary for Token Factory analytics and billing dashboards | Gap Register, Unified IAM/Billing, Token Factory Gateway | Medium | - | Data Platform | |
| OD-013 | When to physically rename/extract `auth` into an IAM service facade | PSSM, Unified IAM/Billing | Medium | OD-002, OD-003 | IAM | Resolved by L3: target IAM code paths use `packages/platform/iam` and `packages/platform/auth`; `packages/services/auth` is retired. See `platform-foundation/Platform_Code_And_Deployment_Architecture_v1.md` and `platform-foundation/Platform_Facade_Callsite_Migration_Map_v1.md`. |

Decision dependency invariant: a high-severity decision should not be blocked
only by a lower-severity decision. If that appears, either the blocked-on
decision is under-severitized or the dependency direction is wrong.

## Related Docs

- `platform-foundation/Platform_Shared_Services_Model_v2.md`
- `platform-foundation/Platform_Architecture_Gap_Register_v1.md`
- `Unified_IAM_Billing_Across_Products_v1.md`
- `API_Gateway_Evaluation_v1.md`
- `Token_Factory_Gateway_Product_Model_v1.md`
- `Cert_Manager_Integration_v1.md`