# stephrobert/dsoxlab architecture

> Architecture diagram of the GitHub repository stephrobert/dsoxlab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stephrobert/dsoxlab
- Repository: https://github.com/stephrobert/dsoxlab

## Overview

dsoxlab is a domain-agnostic CLI for discovering declarative training catalogs, provisioning and opening labs, validating actual system state, and tracking learner progress locally. The graph preserves the documented course/challenge workflow, shell and VM runtimes, infrastructure-only use, diagnostics, and catalog authoring. Some command-to-service wiring is not shown in the excerpts; documented workflow edges cite the README, while uncertain implementation links are omitted.

Main entry points: [`src/dsoxlab/services/lab_service.py`](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/services/lab_service.py) (Lab orchestration), [`src/dsoxlab/cli/demarrage.py`](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/cli/demarrage.py) (CLI commands), [`src/dsoxlab/discovery/repo.py`](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/discovery/repo.py) (Catalog discovery), [`src/dsoxlab/discovery/scanner.py`](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/discovery/scanner.py) (Lab scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI experience"]
  node_cli["CLI commands<br/>[demarrage.py]"]
  node_course["Course guide<br/>[parcours.py]"]
  node_diagnostics["Host diagnostics<br/>[diagnostic.py]"]
  node_catalog_commands["Catalog commands<br/>[catalogues.py]"]
end

subgraph group_catalog["Catalog and contracts"]
  node_repo_meta["Catalog metadata<br/>[repo.py]"]
  node_repo_discovery["Catalog discovery<br/>[repo.py]"]
  node_lab_scan["Lab scanner<br/>[scanner.py]"]
  node_lab_contract["Lab definitions<br/>[lab.py]"]
  node_contract_validation["Contract validation<br/>[contract.py]"]
end

subgraph group_execution["Lab execution"]
  node_lab_service["Lab orchestration<br/>[lab_service.py]"]
  node_runtime_select["Runtime selection<br/>[manager.py]"]
  node_shell_runtime["Shell runtime<br/>[shell.py]"]
  node_vm_runtime["VM runtime<br/>[vm.py]"]
  node_service_containers["Lab services<br/>[services.py]"]
  node_infra_inventory["Infrastructure inventory<br/>[inventory.py]"]
  node_terraform["Terraform providers<br/>[terraform.py]"]
end

subgraph group_learner["Validation and progress"]
  node_validation["State validation<br/>[content.py]"]
  node_progress["Progress scoring"]
  node_sessions[("Local history<br/>[store.py]")]
  node_reporting["Results output<br/>[console.py]"]
  node_hints["Hints and costs<br/>[hint.py]"]
end

node_learner_actor(("Learner"))

node_learner_actor -->|"runs commands"| node_cli
node_cli -->|"opens lesson"| node_course
node_cli -->|"runs lab"| node_lab_service
node_cli -->|"checks host"| node_diagnostics
node_cli -.->|"manages catalog"| node_catalog_commands
node_catalog_commands -.->|"discovers labs"| node_repo_discovery
node_repo_discovery -->|"reads metadata"| node_repo_meta
node_repo_discovery -.->|"scans catalog"| node_lab_scan
node_lab_scan -->|"loads definitions"| node_lab_contract
node_contract_validation -->|"checks contract"| node_repo_meta
node_contract_validation -->|"validates catalog"| node_lab_scan
node_lab_service -->|"locates catalog"| node_repo_discovery
node_lab_service -->|"loads lab"| node_lab_scan
node_lab_service -->|"selects runtime"| node_runtime_select
node_runtime_select -->|"builds shell"| node_shell_runtime
node_runtime_select -->|"builds VM"| node_vm_runtime
node_lab_service -.->|"starts services"| node_service_containers
node_vm_runtime -.->|"provisions VM"| node_infra_inventory
node_infra_inventory -->|"routes provider"| node_terraform
node_lab_service -->|"checks system state"| node_validation
node_validation -->|"scores result"| node_progress
node_progress -->|"persists history"| node_sessions
node_progress -.->|"shows score"| node_reporting
node_lab_service -.->|"offers hints"| node_hints
node_learner_actor -->|"requests challenge"| node_lab_service
node_cli -.->|"runs infra-only"| node_infra_inventory

click node_cli "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/cli/demarrage.py"
click node_course "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/cli/parcours.py"
click node_diagnostics "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/cli/diagnostic.py"
click node_catalog_commands "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/cli/catalogues.py"
click node_repo_meta "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/models/repo.py"
click node_repo_discovery "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/discovery/repo.py"
click node_lab_scan "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/discovery/scanner.py"
click node_lab_contract "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/models/lab.py"
click node_contract_validation "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/validators/contract.py"
click node_lab_service "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/services/lab_service.py"
click node_runtime_select "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/runtimes/manager.py"
click node_shell_runtime "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/runtimes/shell.py"
click node_vm_runtime "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/runtimes/vm.py"
click node_service_containers "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/runtimes/services.py"
click node_infra_inventory "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/infra/inventory.py"
click node_terraform "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/infra/terraform.py"
click node_validation "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/validators/content.py"
click node_progress "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/services/progress_service.py"
click node_sessions "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/sessions/store.py"
click node_reporting "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/reporting/console.py"
click node_hints "https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/models/hint.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_course,node_diagnostics,node_catalog_commands toneBlue
class node_repo_meta,node_repo_discovery,node_lab_scan,node_lab_contract,node_contract_validation toneAmber
class node_lab_service,node_runtime_select,node_shell_runtime,node_vm_runtime,node_service_containers,node_infra_inventory,node_terraform toneMint
class node_validation,node_progress,node_sessions,node_reporting,node_hints toneRose
class node_learner_actor toneIndigo
```

## Components

### CLI experience

- [CLI commands](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/cli/demarrage.py): `src/dsoxlab/cli/demarrage.py`
- [Course guide](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/cli/parcours.py): `src/dsoxlab/cli/parcours.py`
- [Host diagnostics](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/cli/diagnostic.py): `src/dsoxlab/cli/diagnostic.py`
- [Catalog commands](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/cli/catalogues.py): `src/dsoxlab/cli/catalogues.py`

### Catalog and contracts

- [Catalog metadata](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/models/repo.py): `src/dsoxlab/models/repo.py`
- [Catalog discovery](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/discovery/repo.py): `src/dsoxlab/discovery/repo.py`
- [Lab scanner](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/discovery/scanner.py): `src/dsoxlab/discovery/scanner.py`
- [Lab definitions](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/models/lab.py): `src/dsoxlab/models/lab.py`
- [Contract validation](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/validators/contract.py): `src/dsoxlab/validators/contract.py`

### Lab execution

- [Lab orchestration](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/services/lab_service.py): `src/dsoxlab/services/lab_service.py`
- [Runtime selection](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/runtimes/manager.py): `src/dsoxlab/runtimes/manager.py`
- [Shell runtime](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/runtimes/shell.py): `src/dsoxlab/runtimes/shell.py`
- [VM runtime](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/runtimes/vm.py): `src/dsoxlab/runtimes/vm.py`
- [Lab services](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/runtimes/services.py): `src/dsoxlab/runtimes/services.py`
- [Infrastructure inventory](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/infra/inventory.py): `src/dsoxlab/infra/inventory.py`
- [Terraform providers](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/infra/terraform.py): `src/dsoxlab/infra/terraform.py`

### Validation and progress

- [State validation](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/validators/content.py): `src/dsoxlab/validators/content.py`
- [Progress scoring](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/services/progress_service.py): `src/dsoxlab/services/progress_service.py`
- [Local history](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/sessions/store.py): `src/dsoxlab/sessions/store.py`
- [Results output](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/reporting/console.py): `src/dsoxlab/reporting/console.py`
- [Hints and costs](https://github.com/stephrobert/dsoxlab/blob/main/src/dsoxlab/models/hint.py): `src/dsoxlab/models/hint.py`

### Other components

- **Learner**

## Connections

- Learner → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Course guide: opens lesson (evidence: `README.md`)
- CLI commands → Lab orchestration: runs lab (evidence: `README.md`)
- CLI commands → Host diagnostics: checks host (evidence: `README.md`)
- CLI commands → Catalog commands: manages catalog
- Catalog commands → Catalog discovery: discovers labs
- Catalog discovery → Catalog metadata: reads metadata (evidence: `src/dsoxlab/discovery/repo.py`)
- Catalog discovery → Lab scanner: scans catalog (evidence: `src/dsoxlab/discovery/scanner.py`)
- Lab scanner → Lab definitions: loads definitions (evidence: `src/dsoxlab/discovery/scanner.py`)
- Contract validation → Catalog metadata: checks contract (evidence: `src/dsoxlab/validators/contract.py`)
- Contract validation → Lab scanner: validates catalog (evidence: `src/dsoxlab/validators/contract.py`)
- Lab orchestration → Catalog discovery: locates catalog (evidence: `src/dsoxlab/services/lab_service.py`)
- Lab orchestration → Lab scanner: loads lab (evidence: `src/dsoxlab/services/lab_service.py`)
- Lab orchestration → Runtime selection: selects runtime (evidence: `src/dsoxlab/services/lab_service.py`)
- Runtime selection → Shell runtime: builds shell (evidence: `src/dsoxlab/runtimes/manager.py`)
- Runtime selection → VM runtime: builds VM (evidence: `src/dsoxlab/runtimes/manager.py`)
- Lab orchestration → Lab services: starts services
- VM runtime → Infrastructure inventory: provisions VM
- Infrastructure inventory → Terraform providers: routes provider (evidence: `src/dsoxlab/infra/inventory.py`)
- Lab orchestration → State validation: checks system state (evidence: `README.md`)
- State validation → Progress scoring: scores result (evidence: `README.md`)
- Progress scoring → Local history: persists history (evidence: `README.md`)
- Progress scoring → Results output: shows score (evidence: `src/dsoxlab/reporting/console.py`)
- Lab orchestration → Hints and costs: offers hints (evidence: `src/dsoxlab/services/lab_service.py`)
- Learner → Lab orchestration: requests challenge (evidence: `README.md`)
- CLI commands → Infrastructure inventory: runs infra-only (evidence: `src/dsoxlab/cli/demarrage.py`)
