Skip to content

Implementation roadmap

Decided

Source: doc/Implementation_Roadmap.md (1,131 lines) — the master phase plan

The repo organises implementation as pre-phases (gate work that must complete first) followed by numbered phases (each one a vertical slice). Each phase lists its prerequisites, the files to create, the API endpoints to implement, and the tests to write.

Phase model

flowchart TB
    classDef pre fill:#fff3e0,stroke:#e65100
    classDef done fill:#d1e7dd,stroke:#0a3622
    classDef impl fill:#cfe2ff,stroke:#0e2240

    subgraph PRE[Pre-phases — gate work, must complete before features]
        direction TB
        PP1[UX completion before feature coding]:::pre
        PP2[Contract Codegen]:::pre
        PP3[Production Baseline DevOps parallel]:::pre
        PP4[Observability Contract & UX Gate]:::pre
        PP5[Node Agent Secure Node Comms]:::pre
        PP6[Encryption Envelope Baseline]:::pre
        PP7[Tenant Ownership Enforcement Baseline]:::pre
        PP8[Service Accounts Machine Identity Baseline]:::pre
        PP9[Resource Naming Canonical Identifier Baseline]:::pre
        PP10[Frontend UX Foundation Packages]:::pre
    end

    subgraph PHASE[Numbered phases]
        direction TB
        P0["Phase 0 — Foundation"]:::done
        P1[Phase 1 — Test harness + cmd/api wiring]:::impl
        P2[Phase 2 — Auth + Users service]:::impl
        P3[Phase 3 — Inventory service]:::impl
        P4[Phase 4 — Billing service read path]:::impl
        P5[Phase 5 — Payments service]:::impl
        P6[Phase 6 — Provisioning orchestrator]:::impl
        P7[Phase 7 — Provisioning worker]:::impl
        P8[Phase 8 — Billing worker]:::impl
        P9[Phase 9 — Terminal service]:::impl
        P9C[Phase 9C — Hardened Terminal Gateway Extraction]:::impl
        P10[Phase 10 — Storage service]:::impl
        P11[Phase 11 — Admin service]:::impl
        P12[Phase 12 — Notification service]:::impl
        P13[Phase 13 — Integration test harness]:::impl
        P14[Phase 14 — E2E acceptance tests]:::impl
    end

    PRE --> P0
    P0 --> P1
    P1 --> P2

Pre-phases (11) — gate work

Pre-phases are blocking: they must complete before the numbered phases proceed.

# Pre-phase Purpose
1 UX completion before feature coding Screen inventory, state matrix, async UX patterns, terminal UX flow, accessibility baseline
2 Contract Codegen scripts/codegen.sh runs end-to-end, make codegen updates Go + TS without manual edits
3 Production Baseline (DevOps parallel) WAF, TLS rotation, east/west network policy, mTLS, central logs/metrics/traces, KMS, backup/restore
4 Observability Contract & UX Gate OTel + Prom + Tempo + Loki + Grafana selected; admin ops endpoints in OpenAPI; runbook metadata routes
5 Node Agent Secure Node Communication mTLS bootstrap, identity binding, signed tasks
6 Encryption Envelope Baseline KMS-backed envelope encryption for sensitive fields
7 Tenant Ownership Enforcement Baseline tenant→project→resource invariants; ownership tables; per-service DB credentials
8 Service Accounts Machine Identity Baseline project-scoped SA; signing keys; short-lived tokens; rotation
9 Resource Naming Canonical Identifier core42:aicloud:{region}:{tenant}:{project}:... everywhere
10 Frontend UX Foundation Packages Shared UI components, design tokens, contract types

Numbered phases (15)

gantt
    title Phase dependency overview (linear ordering, not calendar)
    dateFormat X
    axisFormat %s
    section Foundation
    Phase 0 — Foundation                   :done,   p0, 0, 1
    section Slices (vertical)
    Phase 1 — Test harness + API wiring    :active, p1, after p0, 2
    Phase 2 — Auth + Users                 :        p2, after p1, 2
    Phase 3 — Inventory                    :        p3, after p2, 2
    Phase 4 — Billing read path            :        p4, after p3, 2
    Phase 5 — Payments                     :        p5, after p4, 2
    Phase 6 — Provisioning orchestrator    :        p6, after p5, 3
    Phase 7 — Provisioning worker          :        p7, after p6, 3
    Phase 8 — Billing worker               :        p8, after p7, 2
    Phase 9 — Terminal service             :        p9, after p8, 2
    Phase 9C — Terminal Gateway Extraction :        p9c, after p9, 1
    Phase 10 — Storage                     :        p10, after p9c, 2
    Phase 11 — Admin                       :        p11, after p10, 2
    Phase 12 — Notification                :        p12, after p11, 2
    section Quality
    Phase 13 — Integration tests           :        p13, after p12, 2
    Phase 14 — E2E acceptance              :        p14, after p13, 2

Phase definition shape (template)

Each phase in the roadmap follows a consistent template — readable at a glance:

mindmap
  root((Phase shape))
    Prerequisites
      pre-phase completions
      dependency phases
      contract baseline
    Read first
      AGENTS.md
      doc/architecture relevant pages
      Coding_Standards.md
    Deliverables
      Files to create
      API endpoints to implement
      DB tables touched
      Tests to write
    Done when
      Definition of Done checklist
      make test passes
      make test-integration passes
      Audit + outbox rows verified
      OpenAPI updated

Vertical-slice strategy

The roadmap explicitly prefers vertical slices over horizontal layering:

flowchart LR
    classDef good fill:#d1e7dd,stroke:#0a3622
    classDef bad fill:#f8d7da,stroke:#42101e

    subgraph V[Vertical slice approach: chosen]
        direction TB
        V1[Pick one user-visible flow:<br/>allocation create]
        V1 --> V2[Carry it through every layer<br/>UX → API → service → DB → worker → node]
        V2 --> V3[Land in main with tests at every layer]
        V3 --> V4[Pick next flow]
    end
    subgraph H[Horizontal layer approach: rejected]
        direction TB
        H1[Build all DB schema first]
        H1 --> H2[Then all services]
        H2 --> H3[Then all APIs]
        H3 --> H4[Then UI]
        H4 --> H5[Integration risk concentrated at end]
    end

    V -.preferred.-> CH[Why: each merge ships<br/>user-visible value;<br/>contract issues found early]:::good
    H -.rejected.-> CH2[Why not: integration risk<br/>concentrated at end;<br/>contract drift catches up late]:::bad

    class V1,V2,V3,V4 good
    class H1,H2,H3,H4,H5 bad

→ Source: Implementation_Roadmap.md §UX + API Vertical Slice Strategy

Dependency graph (summary)

flowchart TB
    classDef pre fill:#fff3e0,stroke:#e65100
    classDef phase fill:#cfe2ff,stroke:#0e2240
    classDef test fill:#e8f5e9,stroke:#2e7d32

    PRE[All pre-phases]:::pre --> P0[Phase 0 Foundation]:::phase
    P0 --> P1[1 Test harness + API]:::phase
    P1 --> P2[2 Auth + Users]:::phase
    P2 --> P3[3 Inventory]:::phase
    P3 --> P4[4 Billing read]:::phase
    P4 --> P5[5 Payments]:::phase
    P3 --> P6[6 Provisioning orch]:::phase
    P6 --> P7[7 Provisioning worker]:::phase
    P4 --> P8[8 Billing worker]:::phase
    P7 --> P9[9 Terminal service]:::phase
    P9 --> P9C[9C Terminal Gateway]:::phase
    P2 --> P10[10 Storage]:::phase
    P2 --> P11[11 Admin]:::phase
    P12[12 Notification]:::phase
    P5 & P8 & P9 --> P12
    P12 --> P13[13 Integration tests]:::test
    P13 --> P14[14 E2E acceptance]:::test

CI portability rule

Every phase must keep gate logic in scripts/ci/*.sh. CI workflow files (.gitlab-ci.yml or GitHub Actions) are orchestration wrappers only. If CI host changes, reuse the scripts and only adapt runner/secret wiring.

→ Cross-reference: CI gates

Companion docs

Doc Role
doc/Execution_Progress.md Live ledger — commit-level completion mapped to phases
doc/Phase_Readiness_Tracker.md Phase signoff state
doc/Detailed_Implementation_Plan.md More granular per-phase plan
doc/Implementation_Sequence.md Sequencing decisions and rationale
doc/governance/Agent_Work_Queue.yaml Current task queue (machine-readable)
doc/Release_Go_NoGo_Checklist.md Production launch gate

Where to look next