Developer Implementation Map designed
Use this page when you are about to change code and need to answer four questions quickly:
- Which contract or route owns the change?
- Which service or package should I edit?
- Which state machine or sequence constrains the behavior?
- Which tables, events, and readbacks prove the result?
Start Order
- Developer APIs for public contract and error model.
- Domain Ownership for team and route boundary.
- System Overview for runtime/C4 shape.
- State Machines for lifecycle and failure semantics.
- Detailed Design Index for deeper canonical design packets.
Engineering Questions To Route
| If you need to answer... | Start here | Canonical authority |
|---|---|---|
| Which API or event shape changes first? | Developer APIs | doc/api/openapi.draft.yaml, doc/api/asyncapi.draft.yaml |
| Which route file or domain owns the behavior? | Domain Ownership | API_Domain_Authoring_Model_v1.md, API_Route_Modularization_and_V1_Freeze_v1.md |
| Which runtime component is on the critical path? | System Overview | Architecture_v1.md, Inter_Service_Communication.md |
| Which state transitions and failed states are allowed? | State Machines | State_Machines.md |
| Which deeper packet should I read next? | Detailed Design Index | the matching canonical design family |
| Which tables and ownership boundaries are involved? | Data model section below | ERD.md, db_schema_v1.sql, schema-ownership.md |
Runtime Structure
Treat the current platform as a contract-first control plane with explicit shared-service boundaries, not as a pile of handlers.
What this means for code changes
- Public behavior changes start in contract artifacts.
- Durable state changes belong in the owning domain package and schema.
- Cross-domain reactions should flow through outbox, events, or explicit shared services, not ad hoc table joins.
- Worker logic should preserve the state machine and retry model, not bypass it.
State And Failure Model
For any workflow change, identify the state machine before touching code.
| Area | Primary state/failure source | Why it matters |
|---|---|---|
| Allocation lifecycle | State_Machines.md | governs happy path, failure path, release retry, billing stop conditions |
| Node/provider activity | State_Machines.md, provider runbooks | determines whether cleanup, release, or recovery is automatic or manual |
| Billing integrity | billing/ledger packets | prevents mutable-balance shortcuts or destructive correction paths |
| Session/access behavior | terminal/session architecture | constrains auth, token use, expiry, and close behavior |
Implementation rule: if you cannot point to the state transition you are changing, you are probably editing the wrong layer.
Sequence Model
Use portal sequence diagrams first, then the canonical packet.
| Sequence need | Portal route | Source note |
|---|---|---|
| High-level user launch/release/onboarding | Architecture Review Pack | curated and current for review/implementation entry |
| Runtime call boundaries | System Overview | derived from current architecture corpus |
| Prototype-era sequence reference | source docs only | Sequence_Flows.md is explicitly reference-only, not target-state authority |
That distinction matters. Developers should not implement from
Sequence_Flows.md blindly; use it only as historical context when a newer
portal/canonical packet does not already answer the question.
Data Model And Ownership
GPUaaS is data-sensitive enough that developers need a direct path to the model, not just a list of tables.
Use the data model in this order
- Read the ER and entity intent in
ERD.md. - Confirm actual column/constraint shape in
db_schema_v1.sql. - Confirm which lane/domain owns the schema in
platform-foundation/ownership-maps/schema-ownership.md.
Data questions
| Question | Primary source |
|---|---|
| What business entity should hold this field? | ERD.md |
| What is the actual deployed schema shape? | db_schema_v1.sql |
| Which domain owns this table or schema family? | schema-ownership.md |
| Can I join this directly from another domain? | ownership map plus service-boundary rules |
Implementation rule: the ERD explains intent, the SQL explains reality, and the schema ownership map explains who is allowed to change it.
Contracts, Routes, And Code Boundaries
| Change type | First edit | Follow-on implementation |
|---|---|---|
| Public API response/request | OpenAPI artifact | handler/service/read-model updates plus codegen |
| Domain event payload | AsyncAPI artifact | outbox payload publisher and consumer updates |
| Shared platform behavior | architecture/shared-service packet | owning shared-service package and guard/evidence path |
| Product route ownership | route/domain authoring docs | route file and domain package |
| New user-visible flow | UX/product journey + contract | web UI, API, readback, UAT coverage |
Developer Definition Of Done
Before calling implementation complete, a developer should be able to show:
- contract and codegen updated when behavior changed;
- owning route/domain is clear;
- state/failure behavior matches the documented machine;
- data model change respects schema ownership;
- readback/UAT/evidence path exists for the changed flow;
- observability and operator surfaces are still coherent.
Developer Escalation Paths
| Problem | Next step |
|---|---|
| You need more detail than the portal summary | Detailed Design Index |
| You need implementation authority for a flow | source doc listed in the matching SourceList |
| You need operator/runtime validation | Operations Team Guide |
| You need user/admin journey coverage | Product Team Guide and Use AI Cloud |
Canonical sources