# Platform Foundation Architecture

Status: active architecture track
Owner: Platform Architecture
Last updated: 2026-06-03

## Purpose

This directory is the start point for the AI Factory platform foundation work.
It groups the architecture documents that define shared services, production
readiness, code ownership, deployment topology, and the gap roadmap.

These documents are architecture records and implementation planning inputs.

## Implementation Snapshot

Fairway track: `PLATFORM-FOUNDATION-OWNERSHIP`

Current state as of 2026-06-01:

- Phase A architecture maps: complete.
- Phase B evidence/status first slice: complete.
- Phase C IAM and registry foundation: complete.
- Phase D product package alignment: complete.
- Phase E deployment extraction readiness: complete.
- Phase F guard graduation: complete.
- PSS operationalization: complete.
- PSSM v2 completion phases 1-6: complete.

The track now has 61/61 tasks marked done in Fairway. The completed baseline is
not a signal to start physical service extraction. It means the ownership maps,
guards, facades, read models, registry seed/facade, App SDK manifest validator,
release evidence gates, and first extraction readiness packet are in place
enough for the next implementation lanes to use them as guardrails.

Next work should be opened as narrower follow-on epics that consume this
foundation, such as billing/audit platformization, App SDK example smoke,
service-auth implementation, or evidence/status extraction hardening.

The PSSM v2 completion track is also complete. Follow-on implementation should
now use the completion artifacts as inputs rather than reopening a broad
platform-foundation reshuffle.

## Reading Order

1. `AI_Factory_Production_Readiness_Gap_Portfolio_v1.md`
   - consolidated readiness and architecture gap view;
   - prioritizes gaps by production readiness, public launch readiness, and
     multi-product scale.
2. `Platform_Shared_Services_Model_v2.md`
   - defines platform shared services versus product-owned domains;
   - identifies registries, evidence, App SDK readiness, and extraction
     trajectory.
3. `Platform_Shared_Services_Completion_Roadmap_v1.md`
   - defines the remaining tracks and phases required to complete PSSM v2 after
     the foundation baseline.
4. `Platform_Code_And_Deployment_Architecture_v1.md`
   - defines target package layout, route ownership, schema ownership, event
     ownership, deployment phases, frontend ownership, and import rules.
5. `Platform_Architecture_Gap_Register_v1.md`
   - compact register of cross-cutting platform gaps and near-term decisions.
6. `Platform_Foundation_Orchestrator_Work_Plan_v1.md`
   - agent/orchestrator execution plan for maps, guards, first slices, and
     safe code movement.
7. `Platform_Foundation_Boundary_Guards_v1.md`
   - report-only guard plan for import boundaries, route placement, schema
     owners, event owners, frontend boundaries, and worker/binary ownership.
8. `Platform_Foundation_Guard_Graduation_Plan_v1.md`
   - report-only to warning to blocking calendar, allowed-debt policy, and
     new-versus-legacy violation rules.
9. `Platform_Deployment_Extraction_Readiness_v1.md`
   - Phase E readiness gates for service auth, degradation contracts, worker
     splits, and extraction candidates before any physical service separation.
10. `Platform_Evidence_Status_Slice_v1.md`
   - first platform-owned evidence/status implementation slice contract,
     including release evidence bundles, readiness read models, and UAT product
     invariants.
11. `Platform_Evidence_Status_Schema_v1.md`
   - additive platform-owned persistence schema for evidence bundles, evidence
     items, release gates, invariant coverage, component status, and guard
     reports.
12. `Platform_Evidence_Status_Frontend_Contract_v1.md`
   - V3 frontend page contract for evidence bundles, UAT invariants, guard
     reports, component readiness, residual risk, and app-developer evidence.
13. `Platform_Registry_Contract_v1.md`
   - product, scope, usage-unit, audit-action, notification-template,
     evidence-type, artifact-type, and App SDK contract registry baseline.
14. `App_SDK_Readiness_Matrix_v1.md`
   - App SDK manifest, launch, connect, publish, failure, and UAT readiness
     matrix.
15. `Product_Onboarding_Checklist_v1.md`
   - next-product onboarding checklist for scopes, usage units, audit,
     notifications, evidence, status, artifacts, SDK, portal, and extraction
     posture.
16. `Product_Onboarding_Executable_Packet_v1.md`
   - required packet fields, fail-closed validation, execution stages, review
     matrix, and next-product example.
17. `Platform_Policy_Quota_Capacity_Composition_v1.md`
   - cross-product policy/quota scope order, quota dimensions, capacity
     reservation posture, and decision evidence.
18. `Platform_Runtime_Reconciliation_Evidence_Model_v1.md`
   - shared reconciliation evidence model for provider/runtime drift, orphan
     cleanup, quarantine, retry, and API/read-model verification.
19. `Platform_Usage_Analytics_OLTP_OLAP_Boundary_v1.md`
   - hot OLTP usage/rating boundary, rollup dimensions, token/request analytics
     path, and dashboard query rules.
20. `Platform_Release_Profile_Gates_v1.md`
   - environment/release profile gate families, profile matrix, evidence
     payload, and gate graduation rule.
21. `../../operations/Platform_Service_Level_CI_CD_Operating_Model_v1.md`
   - post-PSSM CI/CD operating model for global gates, domain-local gates,
     consumer smokes, service evidence, and independent promotion eligibility.
22. `Notification_Policy_Portal_Surface_Model_v1.md`
   - Phase 5 shared-surface model for notification templates, delivery intent,
     policy/entitlement snapshots, quota composition, tenant customization, and
     portal publication tracks.
23. `Secrets_PKI_Runtime_Trust_Model_v1.md`
   - Phase 6 runtime-trust model for secret purpose, credential delivery, cert
     lifecycle evidence, rotation evidence, and extraction decision posture.
24. `Security_Architecture_Current_State_v1.md`
   - current security architecture package for active controls, partial
     controls, future regulated-profile controls, and explicit non-claims.
25. `ownership-maps/`
   - Phase A map artifacts for packages, routes, schema, events, frontend
     surfaces, and worker/binary ownership.

## Which Document To Use

| Question | Primary document | Notes |
|---|---|---|
| Planning the quarter or explaining production-readiness priorities | `AI_Factory_Production_Readiness_Gap_Portfolio_v1.md` | Consolidated readiness view across release, security, UAT, shared services, frontend alignment, and operating separation. |
| Picking up an architecture mode or cross-cutting platform gap | `Platform_Architecture_Gap_Register_v1.md` | Canonical M1-M19 register for architecture gaps. The older top-level gap register is retired in favor of this file. |
| Deciding what shared service owns a capability | `Platform_Shared_Services_Model_v2.md` | Canonical shared-services model. v1 is retained only as historical context. |
| Planning the remaining PSSM v2 work after foundation | `Platform_Shared_Services_Completion_Roadmap_v1.md` | Tracks and phases for operating record, service auth, billing/metering, SDK/artifacts, notification/policy, portal, and extraction hardening. |
| Deciding where code, routes, events, or tables should live | `Platform_Code_And_Deployment_Architecture_v1.md` | Package, route, schema, event, and deployment ownership target. |
| Giving work to an orchestrator or agent lane | `Platform_Foundation_Orchestrator_Work_Plan_v1.md` | Execution sequence, lane ownership, guard graduation, and first queue shape. |
| Turning ownership maps into report-only checks | `Platform_Foundation_Boundary_Guards_v1.md` | Guard catalog, report artifact shape, false-positive handling, and report-to-warning-to-blocking graduation criteria. |
| Deciding when report-only guards become warning or blocking | `Platform_Foundation_Guard_Graduation_Plan_v1.md` | Calendar triggers, allowed-debt policy, new-versus-legacy behavior, and review requirements. |
| Deciding whether a package/facade should become a separately deployed service or worker | `Platform_Deployment_Extraction_Readiness_v1.md` | Service-auth packet, degradation contracts, worker split criteria, extraction candidate gate, and first candidate recommendation. |
| Reviewing mature shared-service keep/split/extract recommendations | `.fairway/artifacts/platform-shared-services-extraction-packets.yaml` | Active packet set for evidence/status, billing usage ingestion, notification dispatch, artifact trust, service auth, and Secrets/PKI. |
| Starting the first platform implementation slice | `Platform_Evidence_Status_Slice_v1.md` | Evidence bundle, status/readiness read-model, UAT invariant coverage, and target package/route/frontend contracts. |
| Defining first-slice persistence | `Platform_Evidence_Status_Schema_v1.md` | Platform-owned tables and API mapping for evidence/status read models. |
| Designing the V3 evidence/status frontend review surfaces | `Platform_Evidence_Status_Frontend_Contract_v1.md` | Page family, personas, read-model dependencies, table/filter/pagination, states, and evidence drill-downs. |
| Defining shared registry IDs before IAM/App SDK/product onboarding work | `Platform_Registry_Contract_v1.md` | Product, scope, usage-unit, audit-action, notification-template, evidence-type, artifact-type, and App SDK contract registry baseline. |
| Deciding whether an app change belongs in runtime code, manifest/SDK, or developer contract | `App_SDK_Readiness_Matrix_v1.md` | Change classification, supported app readiness, SDK gaps, and first implementation recommendations. |
| Onboarding the next product without rebuilding shared services | `Product_Onboarding_Checklist_v1.md` | Checklist for scopes, usage units, audit actions, notifications, evidence, status, artifacts, SDK, portal, and extraction posture. |
| Turning product onboarding into a reviewable execution packet | `Product_Onboarding_Executable_Packet_v1.md` | Required packet YAML, fail-closed validation, stages, review matrix, and minimal Token Factory example. |
| Composing cross-product policy, quota, and capacity decisions | `Platform_Policy_Quota_Capacity_Composition_v1.md` | Scope order, decision input/output, quota dimensions, capacity reservations, and mutation evidence rules. |
| Proving provider/runtime reconciliation without repeated direct SQL | `Platform_Runtime_Reconciliation_Evidence_Model_v1.md` | Drift classification, evidence records, cleanup/quarantine posture, read-model expectations, and release/UAT gates. |
| Extracting MAAS reads or mutations that need GPUaaS node/allocation state | `MAAS_GPUaaS_Read_Model_Contract_v1.md` | Dependency-inverted contract for MAAS to consume GPUaaS lifecycle state without platform-to-product imports or direct product-table ownership. |
| Separating hot usage/rating paths from analytics dashboards | `Platform_Usage_Analytics_OLTP_OLAP_Boundary_v1.md` | OLTP/OLAP boundary, rollup dimensions, token/request analytics path, retention posture, and dashboard query rules. |
| Deciding what each release profile must prove | `Platform_Release_Profile_Gates_v1.md` | Gate families, profile matrix, required evidence payload, failure handling, existing script mapping, and graduation rule. |
| Planning service-level CI/CD after PSSM maturity | `../../operations/Platform_Service_Level_CI_CD_Operating_Model_v1.md` | Global contract gates, domain-local gates, consumer smokes, service evidence, ownership-map routing, and independent promotion eligibility. |
| Preventing notification, policy, quota, tenant, or portal publication forks | `Notification_Policy_Portal_Surface_Model_v1.md` | Phase 5 model for template registry, delivery intent, policy snapshots, quota composition, tenant customization, and internal/customer/partner/public tracks. |
| Deciding runtime trust, Secrets/PKI, rotation evidence, or extraction posture | `Secrets_PKI_Runtime_Trust_Model_v1.md` and `Platform_Deployment_Extraction_Readiness_v1.md` | Phase 6 model for secret purpose, credential delivery, cert/secret rotation evidence, and keep/split/extract packet requirements. |
| Explaining current security architecture without stale whitepaper claims | `Security_Architecture_Current_State_v1.md` | Canonical current-state security package. Separates active controls, partial controls, future regulated-profile work, and non-claims. |
| Checking decisions that are not yet closed | `../Platform_Architecture_Open_Decisions_v1.md` | OD-* register for decision-pending items that can block or reshape implementation. |

## Boundary

This directory owns the foundation-level architecture for:

- production readiness architecture;
- platform shared-service boundaries;
- product versus platform code ownership;
- modular-monolith to extracted-service trajectory;
- platform evidence, status, IAM, billing, audit, notification, registry,
  artifact, policy, and developer-readiness boundaries;
- alignment with frontend platform/product surfaces.

Detailed domain specs remain in their existing architecture, product,
operations, and governance locations.

Frontend has its own architecture work plan in
`../Frontend_Surface_Architecture_Work_Plan_v1.md`. This directory aligns with
that plan for platform/product surfaces; it does not own the full frontend
migration plan.

## Implementation Order Invariant

Platform foundation work must proceed in this order:

1. maps first;
2. guard visibility second;
3. facade implementation third.

Ownership maps define the current and target owners for packages, routes,
schemas, events, workers, and frontend surfaces. Report-only guards make drift
visible before enforcement. Facades and package moves start only after the maps
and guard output are reviewed, so the first implementation slice follows the
architecture instead of creating a new one-off pattern.

Every phase must also produce an executable or reviewable artifact: a map, a
guard report, a facade, a read model, a CI/report artifact, or a reviewed
contract. Avoid broad "alignment" tasks unless they create one of those outputs
and can be checked by Fairway, CI, or architecture review.

The first implementation slice remains platform evidence/status because it
turns UAT, release, security, and operator signals into durable platform-owned
state without requiring risky deployment separation.

## Status

| Document | Status | Use |
|---|---|---|
| `AI_Factory_Production_Readiness_Gap_Portfolio_v1.md` | active planning input | quarterly/platform-readiness planning |
| `Platform_Shared_Services_Model_v2.md` | active target model | shared-service ownership and product composition |
| `Platform_Shared_Services_Completion_Roadmap_v1.md` | active roadmap | remaining PSSM v2 tracks and phases after foundation |
| `Platform_Code_And_Deployment_Architecture_v1.md` | active target architecture | package, route, schema, event, deployment boundaries |
| `Platform_Architecture_Gap_Register_v1.md` | active canonical register | M1-M19 architecture gaps |
| `Platform_Foundation_Orchestrator_Work_Plan_v1.md` | completed execution baseline | agent/orchestrator sequencing |
| `Platform_Foundation_Guard_Graduation_Plan_v1.md` | active governance plan | guard graduation calendar and allowed-debt policy |
| `Platform_Deployment_Extraction_Readiness_v1.md` | active architecture plan | Phase E service-auth, degradation, worker split, and extraction gates |
| `Platform_Evidence_Status_Frontend_Contract_v1.md` | active frontend contract | V3 evidence/status frontend page contract |
| `Platform_Registry_Contract_v1.md` | active contract baseline | shared registry families and first seed-backed entries |
| `App_SDK_Readiness_Matrix_v1.md` | active readiness baseline | App SDK manifest, launch, connect, publish, failure, and UAT readiness |
| `Product_Onboarding_Checklist_v1.md` | active checklist | next-product shared-service onboarding |
| `Product_Onboarding_Executable_Packet_v1.md` | active execution packet | product-neutral onboarding packet and fail-closed validation |
| `Platform_Policy_Quota_Capacity_Composition_v1.md` | active architecture contract | cross-product policy/quota/capacity composition |
| `Platform_Runtime_Reconciliation_Evidence_Model_v1.md` | active architecture contract | provider/runtime reconciliation evidence and API-first verification |
| `Platform_Usage_Analytics_OLTP_OLAP_Boundary_v1.md` | active architecture contract | hot usage/rating versus analytics rollup boundary |
| `Platform_Release_Profile_Gates_v1.md` | active release contract | environment and release-profile evidence gates |
| `../../operations/Platform_Service_Level_CI_CD_Operating_Model_v1.md` | active operating model | post-PSSM service/domain-level CI/CD model |
| `Notification_Policy_Portal_Surface_Model_v1.md` | active Phase 5 contract | notification, policy, quota, tenant, and portal shared-surface model |
| `Secrets_PKI_Runtime_Trust_Model_v1.md` | active Phase 6 contract | secret purpose, credential delivery, rotation evidence, and extraction posture |
| `../Platform_Shared_Services_Model_v1.md` | superseded historical reference | retained for traceability only |

## ID Dictionary

| Prefix | Meaning | Primary location |
|---|---|---|
| `OD-*` | open architectural decision | `../Platform_Architecture_Open_Decisions_v1.md` |
| `M*` | architecture gap/mode | `Platform_Architecture_Gap_Register_v1.md` |
| `PSS-*` | platform shared-service work package | `Platform_Shared_Services_Model_v2.md` |
| `*-PLATFORM-*` | orchestrator/agent execution task | `Platform_Foundation_Orchestrator_Work_Plan_v1.md` and `../../governance/Agent_Work_Queue.yaml` |

## Terminology

| Term | Meaning in this directory |
|---|---|
| AI Factory platform | The overall product platform that can host GPUaaS, App Platform, Token Factory, and future products. |
| Platform shared services | Reusable IAM, billing, audit, evidence, status, notification, registry, artifact, secrets, and policy capabilities consumed by products. |
| Platform Architecture / Platform team | The ownership group for the shared-service model and cross-product architecture decisions. |
| Platform-control release | The governed release/promotion flow for platform-control environments and branches. |

## Related Source Areas

- `../Monorepo_Structure.md`
- `../API_Domain_Authoring_Model_v1.md`
- `../API_Route_Modularization_and_V1_Freeze_v1.md`
- `../Frontend_Surface_Architecture_Work_Plan_v1.md`
- `../../operations/GPUaaS_Security_CD_Current_State_Gap_Roadmap_v1.md`
- `../../operations/Production_Platform_Baseline.md`
- `../../product/GPUaaS_Documentation_and_Developer_Portal_Docusaurus_v1.md`
- `../../governance/Platform_Control_Release_Promotion_Policy.md`