Detailed Implementation Plan (Item 3)

Status

• Historical planning artifact retained for traceability.
• Use Implementation_Roadmap.md for canonical phased build order.
• Use governance/Agent_Work_Queue.yaml and Execution_Progress.md for current execution state.

Scope

This plan covers implementation kickoff after architecture/docs readiness.

Preconditions

• ADR set frozen
• CI platform selected (GitHub or GitLab)
• Contract artifacts frozen for sprint start (openapi.draft.yaml, asyncapi.draft.yaml)

Execution Model

• Bounded-context delivery in vertical slices.
• Contract-first: spec update precedes code changes.
• Agent-generated work must pass policy + CI gates.

Workstreams

1. Platform Foundation
2. Identity and Access
3. Inventory and Allocation Core
4. Provisioning Workflow
5. Billing and Ledger
6. Payments/Webhooks
7. Storage API
8. Terminal Gateway
9. Observability and Ops

Sprint 0 (Setup, 3-5 days)

Goals

• Wire CI pipeline from selected template.
• Stand up local-dev stack.
• Bootstrap service skeletons and shared libraries.

Deliverables

• Active CI workflow file in repo.
• Contract lint and validation jobs passing.
• Local stack bootstraps end-to-end.
• Base service template with logging/tracing/error envelope.

Exit Criteria

• PR with no feature code can pass all mandatory gates.

Sprint 1 (Core API + Data, 1-2 weeks)

Goals

• Implement auth/profile endpoints.
• Implement SKU/nodes/allocations read APIs.
• Implement schema init and repository layer.

Deliverables

• Identity + catalog read paths in production-grade code.
• DB integration and migration tooling baseline.
• Contract tests for implemented endpoints.

Exit Criteria

• Endpoints pass unit/integration/contract tests.
• AuthZ and tenant scoping checks enforced.

Sprint 2 (Provision/Release + Billing Base, 1-2 weeks)

Goals

• Implement allocation provision/release workflow.
• Implement usage record lifecycle and ledger posting base.

Deliverables

• Async provisioning workflow and compensation hooks.
• Billing debit engine (windowed idempotent processing).
• Force-release policy wiring.

Exit Criteria

• Provision->active->release flow stable in integration tests.
• Ledger invariants pass for billing flows.

Sprint 3 (Payments + Storage + Terminal, 1-2 weeks)

Goals

• Implement Stripe session + webhook idempotency.
• Implement storage CRUD APIs.
• Implement terminal gateway contract path.

Deliverables

• Payment crediting flow with replay safety.
• Storage path safety checks and tests.
• Terminal session authz and streaming path.

Exit Criteria

• Critical user journey E2E tests pass.
• Security and abuse-case tests pass for these surfaces.

Sprint 4 (Hardening + Launch Readiness)

Goals

• Complete runbooks, alerts, dashboards.
• Run perf, security, and resilience tests.
• Close Go/No-Go checklist.

Deliverables

• SLO alerting in place.
• Pen-test findings triaged/remediated.
• Final release readiness review artifacts.

Exit Criteria

• Release_Go_NoGo_Checklist.md all mandatory checks pass.

Agent Work Item Template

• Context and bounded context name
• Contract refs (OpenAPI/AsyncAPI sections)
• Data model refs (ERD + SQL)
• Security controls applicable
• Tests required (unit/integration/contract)
• DoD checklist

Definition of Done (Per Story)

• Contract updated (if behavior changed)
• Code implemented with authz/idempotency requirements
• Unit + integration + contract tests added
• Observability hooks added (logs/traces/metrics)
• Docs updated (if architectural/runtime behavior changed)

Parallelization Guidance (Small Team + Agents)

• Run at most 2 core feature streams concurrently.
• Keep one shared foundation stream for CI/contracts/data.
• Avoid concurrent schema-changing stories unless coordinated.

Risks and Mitigations

• Contract drift risk -> enforce CI blocking on contract checks.
• Security regression risk -> required security scans + abuse tests.
• Async complexity risk -> strict event taxonomy + compensation matrix adherence.