# educationwarehouse/edwh architecture

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

- Interactive diagram: https://gitdiagram.com/educationwarehouse/edwh
- Repository: https://github.com/educationwarehouse/edwh

## Overview

edwh is a Python task-runner and maintenance CLI for development projects. Its principal workflow is a user invoking a command, with ewok loading core tasks, plugins, and local tasks, then running project maintenance actions and reporting results. Major documented capabilities include plugin management, project discovery, lint/format/test tasks, release routing, sudo credential setup, and branch worktrees. Source excerpts support the CLI/task-loading boundary, worktree orchestration, pipeline rendering, and plugin/release behavior; several other task internals are unsampled, so their internal call links are intentionally limited.

Main entry points: [`src/edwh/local_tasks/worktree.py`](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/local_tasks/worktree.py) (Worktree Tasks), [`src/edwh/tasks.py`](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/tasks.py) (Core Tasks), [`src/edwh/cli.py`](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/cli.py) (CLI App), [`src/edwh/local_tasks/plugin.py`](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/local_tasks/plugin.py) (Plugin Tasks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command Runtime"]
  node_cli["CLI App<br/>[cli.py]"]
  node_core_tasks["Core Tasks<br/>[tasks.py]"]
  node_task_discovery["Task Discovery<br/>[discover.py]"]
end

subgraph group_maintain["Project Maintenance"]
  node_project_ops["Project Operations<br/>[tasks.py]"]
  node_discovery_output["Project Inventory<br/>[discover.py]"]
end

subgraph group_worktrees["Worktree Environments"]
  node_worktree_tasks["Worktree Tasks<br/>[worktree.py]"]
  node_project_config["Project Configuration"]
  node_database_seed["Database Seeding<br/>[worktree.py]"]
end

subgraph group_extensions["Plugins And Release"]
  node_plugins["Plugin Tasks<br/>[plugin.py]"]
  node_plugin_registry[("Plugin Packages")]
  node_release_router["Release Routing<br/>[release_backend.py]"]
end

subgraph group_execution["Execution Feedback"]
  node_pipeline["Step Runner<br/>[pipeline.py]"]
  node_renderer["Terminal Renderer<br/>[tui.py]"]
end

node_developer(("Developer"))
node_pypi["PyPI"]
node_vommit["vommit"]
node_keyring[("OS Keyring")]
node_ssh_agent["SSH Agent"]
node_git["Git Worktrees"]
node_compose["Compose Services"]
node_lint_tools["Ruff And Ty"]
node_pytest["Pytest"]

node_developer -->|"invokes"| node_cli
node_cli -->|"loads"| node_core_tasks
node_cli -->|"loads"| node_plugins
node_cli -->|"loads"| node_worktree_tasks
node_core_tasks -->|"runs discovery"| node_task_discovery
node_task_discovery -->|"produces inventory"| node_discovery_output
node_developer -->|"manages plugins"| node_plugins
node_plugins -->|"installs packages"| node_plugin_registry
node_plugins -->|"fetches metadata"| node_pypi
node_developer -->|"requests release"| node_release_router
node_release_router -.->|"delegates release"| node_vommit
node_core_tasks -->|"uses credentials"| node_keyring
node_core_tasks -.->|"configures fallback"| node_ssh_agent
node_developer -->|"manages branches"| node_worktree_tasks
node_worktree_tasks -->|"creates worktree"| node_git
node_worktree_tasks -->|"copies and rewrites"| node_project_config
node_worktree_tasks -->|"runs setup"| node_core_tasks
node_worktree_tasks -->|"starts services"| node_compose
node_worktree_tasks -->|"selects seed"| node_database_seed
node_worktree_tasks -->|"queues steps"| node_pipeline
node_pipeline -->|"sends status"| node_renderer
node_developer -->|"runs maintenance"| node_project_ops
node_project_ops -->|"runs lint"| node_lint_tools
node_project_ops -->|"runs tests"| node_pytest

click node_cli "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/cli.py"
click node_core_tasks "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/tasks.py"
click node_task_discovery "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/discover.py"
click node_plugins "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/local_tasks/plugin.py"
click node_release_router "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/release_backend.py"
click node_worktree_tasks "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/local_tasks/worktree.py"
click node_database_seed "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/local_tasks/worktree.py"
click node_pipeline "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/pipeline.py"
click node_renderer "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/tui.py"
click node_project_ops "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/tasks.py"
click node_discovery_output "https://github.com/educationwarehouse/edwh/blob/main/src/edwh/discover.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_core_tasks,node_task_discovery toneBlue
class node_project_ops,node_discovery_output,node_keyring toneAmber
class node_worktree_tasks,node_project_config,node_database_seed toneMint
class node_plugins,node_plugin_registry,node_release_router toneRose
class node_pipeline,node_renderer,node_developer,node_pypi,node_vommit,node_ssh_agent,node_git,node_compose,node_lint_tools,node_pytest toneIndigo
```

## Components

### Command Runtime

- [CLI App](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/cli.py): `src/edwh/cli.py`
- [Core Tasks](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/tasks.py): `src/edwh/tasks.py`
- [Task Discovery](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/discover.py): `src/edwh/discover.py`

### Project Maintenance

- [Project Operations](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/tasks.py): `src/edwh/tasks.py`
- [Project Inventory](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/discover.py): `src/edwh/discover.py`

### Worktree Environments

- [Worktree Tasks](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/local_tasks/worktree.py): `src/edwh/local_tasks/worktree.py`
- **Project Configuration**
- [Database Seeding](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/local_tasks/worktree.py): `src/edwh/local_tasks/worktree.py`

### Plugins And Release

- [Plugin Tasks](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/local_tasks/plugin.py): `src/edwh/local_tasks/plugin.py`
- **Plugin Packages**
- [Release Routing](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/release_backend.py): `src/edwh/release_backend.py`

### Execution Feedback

- [Step Runner](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/pipeline.py): `src/edwh/pipeline.py`
- [Terminal Renderer](https://github.com/educationwarehouse/edwh/blob/main/src/edwh/tui.py): `src/edwh/tui.py`

### Other components

- **Developer**
- **PyPI**
- **vommit**
- **OS Keyring**
- **SSH Agent**
- **Git Worktrees**
- **Compose Services**
- **Ruff And Ty**
- **Pytest**

## Connections

- Developer → CLI App: invokes
- CLI App → Core Tasks: loads
- CLI App → Plugin Tasks: loads
- CLI App → Worktree Tasks: loads
- Core Tasks → Task Discovery: runs discovery
- Task Discovery → Project Inventory: produces inventory
- Developer → Plugin Tasks: manages plugins
- Plugin Tasks → Plugin Packages: installs packages
- Plugin Tasks → PyPI: fetches metadata
- Developer → Release Routing: requests release
- Release Routing → vommit: delegates release
- Core Tasks → OS Keyring: uses credentials
- Core Tasks → SSH Agent: configures fallback
- Developer → Worktree Tasks: manages branches
- Worktree Tasks → Git Worktrees: creates worktree
- Worktree Tasks → Project Configuration: copies and rewrites
- Worktree Tasks → Core Tasks: runs setup
- Worktree Tasks → Compose Services: starts services
- Worktree Tasks → Database Seeding: selects seed
- Worktree Tasks → Step Runner: queues steps
- Step Runner → Terminal Renderer: sends status
- Developer → Project Operations: runs maintenance
- Project Operations → Ruff And Ty: runs lint
- Project Operations → Pytest: runs tests