# dderyldowney/vde-system architecture

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

- Interactive diagram: https://gitdiagram.com/dderyldowney/vde-system
- Repository: https://github.com/dderyldowney/vde-system

## Overview

VDE is a Docker-based development environment for creating and operating isolated “Spoke” workspaces, with a companion Forge governance system. The documented user path is to bootstrap or invoke the CLI, manage a Spoke through its lifecycle, and work as devuser with workspace files persisted back to the Hub. The graph preserves documented health, service, USB, and schema-validation capabilities. Source excerpts cover only the JSON validator and a tagging utility, so most runtime links below are documented in the README rather than verified from implementation.

Main entry points: [`bin/vde`](https://github.com/dderyldowney/vde-system/blob/develop/bin/vde) (VDE CLI), [`projects`](https://github.com/dderyldowney/vde-system/tree/develop/projects) (Persistent workspace), [`configs/ssh/config`](https://github.com/dderyldowney/vde-system/blob/develop/configs/ssh/config) (SSH bridge), [`.gemini`](https://github.com/dderyldowney/vde-system/tree/develop/.gemini) (Forge governance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_bootstrap["Bootstrap<br/>[bootstrap.sh]"]
  node_cli["VDE CLI"]
  node_health["Hub health"]
  node_spoke_inspection["Spoke inspection"]
end

subgraph group_spokes["Spoke environment"]
  node_lifecycle["Spoke lifecycle"]
  node_language_images["Language Spokes"]
  node_service_images["Service Spokes"]
  node_vm_types["VM type registry<br/>[vm-types.json]"]
end

subgraph group_connections["Workspace and access"]
  node_workspace["Persistent workspace"]
  node_ssh_bridge["SSH bridge"]
  node_usb_mapping["USB mapping<br/>[vde-usb-map.zsh]"]
end

subgraph group_governance["Governance and validation"]
  node_forge_governance["Forge governance<br/>[.gemini]"]
  node_mass_tagger["File tagging<br/>[mass_tagger.py]"]
  node_json_validator["JSON schema validation"]
end

node_student(("Developer"))

node_student -->|"starts setup"| node_bootstrap
node_student -->|"runs commands"| node_cli
node_cli -->|"manages lifecycle"| node_lifecycle
node_lifecycle -.->|"uses Spokes"| node_language_images
node_lifecycle -.->|"uses services"| node_service_images
node_cli -->|"checks health"| node_health
node_cli -->|"inspects Spoke"| node_spoke_inspection
node_student -->|"saves work"| node_workspace
node_workspace -->|"syncs to Hub"| node_ssh_bridge
node_ssh_bridge -->|"connects Hub"| node_student
node_student -->|"uses hardware"| node_usb_mapping
node_student -->|"uses governance"| node_forge_governance
node_forge_governance -.->|"tags files"| node_mass_tagger

click node_bootstrap "https://github.com/dderyldowney/vde-system/blob/develop/scripts/bootstrap.sh"
click node_cli "https://github.com/dderyldowney/vde-system/blob/develop/bin/vde"
click node_lifecycle "https://github.com/dderyldowney/vde-system/blob/develop/bin/vde"
click node_language_images "https://github.com/dderyldowney/vde-system/tree/develop/configs/docker/languages"
click node_service_images "https://github.com/dderyldowney/vde-system/tree/develop/configs/docker/services"
click node_vm_types "https://github.com/dderyldowney/vde-system/blob/develop/data/vm-types.json"
click node_health "https://github.com/dderyldowney/vde-system/blob/develop/bin/vde-health"
click node_spoke_inspection "https://github.com/dderyldowney/vde-system/blob/develop/bin/vde-info"
click node_workspace "https://github.com/dderyldowney/vde-system/tree/develop/projects"
click node_ssh_bridge "https://github.com/dderyldowney/vde-system/blob/develop/configs/ssh/config"
click node_usb_mapping "https://github.com/dderyldowney/vde-system/blob/develop/scripts/vde-usb-map.zsh"
click node_forge_governance "https://github.com/dderyldowney/vde-system/tree/develop/.gemini"
click node_mass_tagger "https://github.com/dderyldowney/vde-system/blob/develop/conductor/mass_tagger.py"
click node_json_validator "https://github.com/dderyldowney/vde-system/blob/develop/lib/vde-json-validate.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_bootstrap,node_cli,node_health,node_spoke_inspection toneBlue
class node_lifecycle,node_language_images,node_service_images,node_vm_types toneAmber
class node_workspace,node_ssh_bridge,node_usb_mapping toneMint
class node_forge_governance,node_mass_tagger,node_json_validator toneRose
class node_student toneIndigo
```

## Components

### User entry

- [Bootstrap](https://github.com/dderyldowney/vde-system/blob/develop/scripts/bootstrap.sh): `scripts/bootstrap.sh`
- [VDE CLI](https://github.com/dderyldowney/vde-system/blob/develop/bin/vde): `bin/vde`
- [Hub health](https://github.com/dderyldowney/vde-system/blob/develop/bin/vde-health): `bin/vde-health`
- [Spoke inspection](https://github.com/dderyldowney/vde-system/blob/develop/bin/vde-info): `bin/vde-info`

### Spoke environment

- [Spoke lifecycle](https://github.com/dderyldowney/vde-system/blob/develop/bin/vde): `bin/vde`
- [Language Spokes](https://github.com/dderyldowney/vde-system/tree/develop/configs/docker/languages): `configs/docker/languages`
- [Service Spokes](https://github.com/dderyldowney/vde-system/tree/develop/configs/docker/services): `configs/docker/services`
- [VM type registry](https://github.com/dderyldowney/vde-system/blob/develop/data/vm-types.json): `data/vm-types.json`

### Workspace and access

- [Persistent workspace](https://github.com/dderyldowney/vde-system/tree/develop/projects): `projects`
- [SSH bridge](https://github.com/dderyldowney/vde-system/blob/develop/configs/ssh/config): `configs/ssh/config`
- [USB mapping](https://github.com/dderyldowney/vde-system/blob/develop/scripts/vde-usb-map.zsh): `scripts/vde-usb-map.zsh`

### Governance and validation

- [Forge governance](https://github.com/dderyldowney/vde-system/tree/develop/.gemini): `.gemini`
- [File tagging](https://github.com/dderyldowney/vde-system/blob/develop/conductor/mass_tagger.py): `conductor/mass_tagger.py`
- [JSON schema validation](https://github.com/dderyldowney/vde-system/blob/develop/lib/vde-json-validate.py): `lib/vde-json-validate.py`

### Other components

- **Developer**

## Connections

- Developer → Bootstrap: starts setup (evidence: `README.md`)
- Developer → VDE CLI: runs commands (evidence: `README.md`)
- VDE CLI → Spoke lifecycle: manages lifecycle (evidence: `README.md`)
- Spoke lifecycle → Language Spokes: uses Spokes
- Spoke lifecycle → Service Spokes: uses services
- VDE CLI → Hub health: checks health (evidence: `README.md`)
- VDE CLI → Spoke inspection: inspects Spoke (evidence: `README.md`)
- Developer → Persistent workspace: saves work (evidence: `README.md`)
- Persistent workspace → SSH bridge: syncs to Hub (evidence: `README.md`)
- SSH bridge → Developer: connects Hub (evidence: `README.md`)
- Developer → USB mapping: uses hardware (evidence: `README.md`)
- Developer → Forge governance: uses governance (evidence: `README.md`)
- Forge governance → File tagging: tags files