[Docs]: architecture.md missing orchestrator package and has stale interface/build references

[mrhillsman]

Documentation Type

Fix incorrect information

Location

docs/architecture.md

Description

docs/architecture.md does not reflect the orchestrator extraction, the Roles() → RoleDistribution() change, the DataVolumeTemplates error return, or the CGO-free build migration. Issues fall into string replacements and structural/mental-model fixes.

String replacements

Line(s)	Current (wrong)	Should be
247	+DataVolumeTemplates() []DataVolumeTemplateSpec	+DataVolumeTemplates() ([]DataVolumeTemplateSpec, error)
267	+DataVolumeTemplates() []DataVolumeTemplateSpec	+DataVolumeTemplates() ([]DataVolumeTemplateSpec, error)
255	+Roles() []string	+RoleDistribution() []RoleSpec
302	+Roles() ["server", "client"]	+RoleDistribution() []RoleSpec
312	+Roles() ["server", "client"]	+RoleDistribution() []RoleSpec
480	namespaceDataVolumes (cmd/virtwork/main.go)	NamespaceDataVolumes (internal/orchestrator/types.go)
548	Multi-stage build (Debian builder + UBI9 runtime)	Multi-stage build (Alpine builder + UBI9 runtime)

Mental model: internal/orchestrator/ is completely absent

The internal/orchestrator/ package (with orchestrator.go, cleanup.go, types.go) does not appear anywhere in the document. This is significant because the orchestrator now owns the errgroup lifecycle, VM planning, resource/secret creation, and readiness polling — all previously attributed to cmd/virtwork/main.go.

Affected locations:

1. Layer 4 mermaid diagram (lines 17-21) — Shows CMD, CLEANUP, AUDIT in Layer 4.

   • AUDIT belongs in Layer 1 (it depends on config and constants, same level as cluster/cloudinit/logging).
   • orchestrator is missing — it belongs in Layer 4 alongside cmd/virtwork and cleanup.
   • Add an ORCH node for internal/orchestrator/orchestrator.go in the Layer 4 subgraph; move AUDIT into the Layer 1 subgraph.

2. Dependency arrows (lines 55-61) — CMD has direct arrows to REGISTRY, VM, RES, WAIT. In reality, main.go delegates to RunOrchestrator which owns those dependencies. The arrows should flow CMD → ORCH → {REGISTRY, VM, RES, WAIT, AUDIT}, and CMD keeps direct arrows to CONFIG, CLUSTER, LOGGING.

3. CMD node label (line 18) — Says "Cobra commands + orchestration." Should say "Cobra commands + dependency wiring" since orchestration lives in internal/orchestrator.

4. Concurrency table (line 178) — cmd/virtwork row says "Owns errgroup lifecycle; spawns goroutines for parallel operations." The RunOrchestrator now owns the errgroup. Add an internal/orchestrator row ("Owns errgroup lifecycle for VM creation and secret creation; coordinates planning, resource creation, and readiness") and update cmd/virtwork to "Wires dependencies, delegates to RunOrchestrator."

5. CLI Orchestration Flow flowchart (lines 184-216) — The step sequence is conceptually correct (matches RunOrchestrator.Run()), but the starting node says "Cobra RunE entry point" with no mention of the orchestrator boundary. Add a node or annotation showing that RunE creates a RunOrchestrator and the subsequent steps execute within ro.Run().

6. Project Structure (lines 488-531) — Missing internal/orchestrator/ directory entirely. Also missing audit/migrate.go from the audit file listing. The main.go comment says "Cobra root + subcommands, orchestration" — should say "Cobra root + subcommands, dependency wiring."

7. Key Design Decisions table (line 480) — References namespaceDataVolumes in cmd/virtwork/main.go.

Mental model: Roles() → RoleDistribution()

Same change as tracked in #172 for the guide files. Roles() returned []string; RoleDistribution() returns []RoleSpec with per-role VM counts.

Affected locations:

• Mermaid Layer 3 node (line 26) — MultiVMWorkload interface\n(Roles, UserdataForRole) → (RoleDistribution, UserdataForRole)
• Class diagram MultiVMWorkload (line 255) — +Roles() []string → +RoleDistribution() []RoleSpec
• Class diagram NetworkWorkload (line 302) — +Roles() ["server", "client"] → +RoleDistribution() []RoleSpec
• Class diagram TPSWorkload (line 312) — +Roles() ["server", "client"] → +RoleDistribution() []RoleSpec

No changes needed

• Configuration Priority Chain diagram — accurate
• SSH Credential Flow diagram — accurate
• Resource Tracking and Cleanup diagram — accurate
• Workload Comparison table — accurate
• Cleanup flowchart — accurate

Suggested Content

• Add ORCH["internal/orchestrator\nRunOrchestrator + helpers"] to Layer 4 subgraph; move AUDIT to Layer 1
• Reroute dependency arrows: CMD → ORCH → {REGISTRY, VM, RES, WAIT}
• Update CMD label to "Cobra commands + dependency wiring"
• Add internal/orchestrator row to concurrency table; update cmd/virtwork row
• Add orchestrator boundary annotation to CLI Orchestration Flow flowchart
• Add orchestrator/ directory and audit/migrate.go to project structure
• Replace all Roles() with RoleDistribution() and []string with []RoleSpec
• Update DataVolumeTemplates signatures to include error return
• Fix Dockerfile description from Debian to Alpine
• Update namespaceDataVolumes → NamespaceDataVolumes with correct file path