# hyper-forge/ghidora architecture

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

- Interactive diagram: https://gitdiagram.com/hyper-forge/ghidora
- Repository: https://github.com/hyper-forge/ghidora

## Overview

Ghidora is a cross-runtime monorepo task orchestrator. A user invokes the TypeScript CLI, which loads workspace configuration, discovers packages and task dependencies, builds or reuses a workspace graph, then schedules tasks and launches package processes. Local and optional cloud caches support task execution; a graph server provides a task-graph view. The Rust/WASM core supplies deterministic hashing and terminal/UI functions. Several subsystem links come from the README or SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`apps/ghidora/src/main.ts`](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/main.ts) (Ghidora CLI), [`apps/ghidora/src/orchestrator/graph-core.ts`](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/graph-core.ts) (Graph assembly), [`apps/ghidora/src/updates/checkForUpdates.ts`](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/updates/checkForUpdates.ts) (Update checker), [`apps/ghidora/src/orchestrator/cloud-cache.ts`](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/cloud-cache.ts) (Cloud task cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and runtime"]
  node_cli["Ghidora CLI<br/>[main.ts]"]
  node_runtime["Runtime helpers<br/>[helper.ts]"]
  node_types["Config and types"]
  node_updates["Update checker<br/>[checkForUpdates.ts]"]
  node_help["CLI help<br/>[ghidoraHelp.ts]"]
end

subgraph group_workspace["Workspace orchestration"]
  node_scaffold["Workspace starters<br/>[starters.ts]"]
  node_discovery["Workspace discovery<br/>[discover.ts]"]
  node_graphcore["Graph assembly<br/>[graph-core.ts]"]
  node_taskgraph["Task dependencies<br/>[graph.ts]"]
  node_executor["Plan execution<br/>[executePlan.ts]"]
  node_graphview["Graph server<br/>[graph-server.ts]"]
end

subgraph group_cache["Task caching"]
  node_graphcache[("Graph cache<br/>[graph-cache.ts]")]
  node_localcache[("Local task cache<br/>[cache.ts]")]
  node_cloudcache["Cloud task cache<br/>[cloud-cache.ts]"]
end

subgraph group_wasm["Rust WASM core"]
  node_wasmcrypto["Hash functions<br/>[crypto.rs]"]
  node_wasmconfig["Templates and graph UI<br/>[config.rs]"]
  node_wasmcli["Terminal UI<br/>[cli.rs]"]
end

node_user(("CLI user"))
node_cloudservice[("Cloud cache service")]
node_registry["Package registry"]

node_user -->|"invokes"| node_cli
node_cli -->|"initializes workspace"| node_scaffold
node_cli -->|"uses runtime helpers"| node_runtime
node_cli -->|"uses config types"| node_types
node_cli -->|"builds workspace graph"| node_discovery
node_cli -->|"builds full graph"| node_graphcore
node_cli -->|"reads graph cache"| node_graphcache
node_cli -->|"uses task graph"| node_taskgraph
node_cli -->|"dispatches plan"| node_executor
node_cli -->|"uses task cache"| node_localcache
node_cli -->|"restores cloud cache"| node_cloudcache
node_cli -->|"uses graph server"| node_graphview
node_cli -->|"checks updates"| node_updates
node_cli -->|"uses help"| node_help
node_graphcore -->|"uses discovery"| node_discovery
node_graphcore -->|"uses task graph"| node_taskgraph
node_cloudcache -->|"fetches and uploads"| node_cloudservice
node_updates -->|"checks latest version"| node_registry
node_wasmcrypto -->|"exported by core"| node_wasmcli
node_wasmconfig -->|"exported by core"| node_wasmcli

click node_cli "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/main.ts"
click node_runtime "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/utils/helper.ts"
click node_types "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/datatypes/validateDataTypes.ts"
click node_scaffold "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/starters.ts"
click node_discovery "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/discover.ts"
click node_graphcore "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/graph-core.ts"
click node_taskgraph "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/graph.ts"
click node_executor "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/executePlan.ts"
click node_graphview "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/graph-server.ts"
click node_graphcache "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/graph-cache.ts"
click node_localcache "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/cache.ts"
click node_cloudcache "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/cloud-cache.ts"
click node_wasmcrypto "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora-core/src/crypto.rs"
click node_wasmconfig "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora-core/src/config.rs"
click node_wasmcli "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora-core/src/cli.rs"
click node_updates "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/updates/checkForUpdates.ts"
click node_help "https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/utils/ghidoraHelp.ts"

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_runtime,node_types,node_updates,node_help,node_user toneBlue
class node_scaffold,node_discovery,node_graphcore,node_taskgraph,node_executor,node_graphview,node_cloudservice toneAmber
class node_graphcache,node_localcache,node_cloudcache toneMint
class node_wasmcrypto,node_wasmconfig,node_wasmcli toneRose
class node_registry toneIndigo
```

## Components

### CLI and runtime

- [Ghidora CLI](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/main.ts): `apps/ghidora/src/main.ts`
- [Runtime helpers](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/utils/helper.ts): `apps/ghidora/src/utils/helper.ts`
- [Config and types](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/datatypes/validateDataTypes.ts): `apps/ghidora/src/datatypes/validateDataTypes.ts`
- [Update checker](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/updates/checkForUpdates.ts): `apps/ghidora/src/updates/checkForUpdates.ts`
- [CLI help](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/utils/ghidoraHelp.ts): `apps/ghidora/src/utils/ghidoraHelp.ts`

### Workspace orchestration

- [Workspace starters](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/starters.ts): `apps/ghidora/src/orchestrator/starters.ts`
- [Workspace discovery](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/discover.ts): `apps/ghidora/src/orchestrator/discover.ts`
- [Graph assembly](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/graph-core.ts): `apps/ghidora/src/orchestrator/graph-core.ts`
- [Task dependencies](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/graph.ts): `apps/ghidora/src/orchestrator/graph.ts`
- [Plan execution](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/executePlan.ts): `apps/ghidora/src/orchestrator/executePlan.ts`
- [Graph server](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/graph-server.ts): `apps/ghidora/src/orchestrator/graph-server.ts`

### Task caching

- [Graph cache](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/graph-cache.ts): `apps/ghidora/src/orchestrator/graph-cache.ts`
- [Local task cache](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/cache.ts): `apps/ghidora/src/orchestrator/cache.ts`
- [Cloud task cache](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora/src/orchestrator/cloud-cache.ts): `apps/ghidora/src/orchestrator/cloud-cache.ts`

### Rust WASM core

- [Hash functions](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora-core/src/crypto.rs): `apps/ghidora-core/src/crypto.rs`
- [Templates and graph UI](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora-core/src/config.rs): `apps/ghidora-core/src/config.rs`
- [Terminal UI](https://github.com/hyper-forge/ghidora/blob/master/apps/ghidora-core/src/cli.rs): `apps/ghidora-core/src/cli.rs`

### Other components

- **CLI user**
- **Cloud cache service**
- **Package registry**

## Connections

- CLI user → Ghidora CLI: invokes (evidence: `README.md`)
- Ghidora CLI → Workspace starters: initializes workspace (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Runtime helpers: uses runtime helpers (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Config and types: uses config types (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Workspace discovery: builds workspace graph (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Graph assembly: builds full graph (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Graph cache: reads graph cache (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Task dependencies: uses task graph (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Plan execution: dispatches plan (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Local task cache: uses task cache (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Cloud task cache: restores cloud cache (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Graph server: uses graph server (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → Update checker: checks updates (evidence: `apps/ghidora/src/main.ts`)
- Ghidora CLI → CLI help: uses help (evidence: `apps/ghidora/src/main.ts`)
- Graph assembly → Workspace discovery: uses discovery (evidence: `apps/ghidora/src/orchestrator/graph-core.ts`)
- Graph assembly → Task dependencies: uses task graph (evidence: `apps/ghidora/src/orchestrator/graph-core.ts`)
- Cloud task cache → Cloud cache service: fetches and uploads (evidence: `apps/ghidora/src/orchestrator/cloud-cache.ts`)
- Update checker → Package registry: checks latest version (evidence: `apps/ghidora/src/updates/checkForUpdates.ts`)
- Hash functions → Terminal UI: exported by core (evidence: `apps/ghidora-core/src/lib.rs`)
- Templates and graph UI → Terminal UI: exported by core (evidence: `apps/ghidora-core/src/lib.rs`)
