# castwell-4439/forge architecture

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

- Interactive diagram: https://gitdiagram.com/castwell-4439/forge
- Repository: https://github.com/castwell-4439/forge

## Overview

Forge is a distributed workflow scheduler and AI-agent framework: users define workflows and submit tasks, the registry compiles workflow YAML into DAGs, the coordinator schedules and routes task execution to workers, and results are persisted and surfaced through APIs and the dashboard. The runtime also supports approvals, event replay and compensation, CDC, distributed coordination, and optional ForgeX run observation and evaluation. The README documents these capabilities; sampled source confirms selected coordinator, HITL, MCP, policy, and product API behavior, but not every runtime connection.

Main entry points: [`internal/coordinator/coordinator.go`](https://github.com/castwell-4439/forge/blob/main/internal/coordinator/coordinator.go) (DAG coordinator), [`internal/agent/harness/loop.go`](https://github.com/castwell-4439/forge/blob/main/internal/agent/harness/loop.go) (Agent runtime), [`internal/forgex/storage/store.go`](https://github.com/castwell-4439/forge/blob/main/internal/forgex/storage/store.go) (Run artifacts), [`internal/worker/worker.go`](https://github.com/castwell-4439/forge/blob/main/internal/worker/worker.go) (Worker runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow runtime"]
  node_registry["YAML registry<br/>[registry.go]"]
  node_scheduler["Workflow scheduler<br/>[scheduler.go]"]
  node_coordinator["DAG coordinator<br/>[coordinator.go]"]
  node_hitl["Approval manager<br/>[manager.go]"]
  node_events[("Event store<br/>[store.go]")]
  node_saga["Saga compensation<br/>[compensator.go]"]
end

subgraph group_execution["Worker execution"]
  node_worker_mgr["Worker manager<br/>[worker_manager.go]"]
  node_worker_runtime["Worker runtime<br/>[worker.go]"]
  node_builtin_workers["Built-in workers<br/>[worker.go]"]
  node_sdk["Worker SDKs<br/>[worker.go]"]
end

subgraph group_platform["Platform services"]
  node_storage[("Metadata storage<br/>[interface.go]")]
  node_bus["Message bus<br/>[nats.go]"]
  node_discovery["Service discovery<br/>[etcd.go]"]
  node_cdc["Change capture<br/>[postgres.go]"]
  node_observability["Observability<br/>[metrics.go]"]
end

subgraph group_agent["Agent framework"]
  node_agent["Agent runtime<br/>[loop.go]"]
  node_planning["Agent planning<br/>[planner.go]"]
  node_rag["Hybrid retrieval<br/>[hybrid.go]"]
  node_mcp["MCP manager<br/>[manager.go]"]
  node_guardrails["Agent guardrails<br/>[injection.go]"]
end

subgraph group_forgex["ForgeX control plane"]
  node_forgex_observer["Runtime observer<br/>[file_observer.go]"]
  node_forgex_policy["Tool policy<br/>[engine.go]"]
  node_forgex_stop["Stop decisions<br/>[engine.go]"]
  node_forgex_api["ForgeX API<br/>[server.go]"]
  node_forgex_store[("Run artifacts<br/>[store.go]")]
  node_forgex_cli["ForgeX CLI<br/>[main.go]"]
end

node_user(("Workflow user"))
node_dashboard["Admin dashboard<br/>[App.tsx]"]
node_postgres[("PostgreSQL")]
node_etcd[("etcd")]
node_nats["NATS"]
node_mcp_servers["MCP servers"]

node_user -->|"defines workflow"| node_registry
node_user -->|"views operations"| node_dashboard
node_dashboard -->|"submits tasks"| node_coordinator
node_registry -->|"compiles DAG"| node_coordinator
node_scheduler -->|"triggers runs"| node_coordinator
node_coordinator -->|"selects workers"| node_worker_mgr
node_worker_mgr -->|"tracks workers"| node_discovery
node_coordinator -->|"dispatches tasks"| node_worker_runtime
node_worker_runtime -->|"runs handlers"| node_builtin_workers
node_sdk -->|"implements workers"| node_worker_runtime
node_coordinator -->|"requests approval"| node_hitl
node_coordinator -->|"records events"| node_events
node_saga -->|"reads run events"| node_events
node_coordinator -->|"persists state"| node_storage
node_coordinator -->|"publishes tasks"| node_bus
node_bus -->|"transfers messages"| node_nats
node_discovery -->|"registers services"| node_etcd
node_cdc -->|"streams WAL changes"| node_postgres
node_coordinator -->|"reports telemetry"| node_observability
node_agent -->|"requests plans"| node_planning
node_agent -->|"retrieves context"| node_rag
node_agent -->|"checks inputs"| node_guardrails
node_agent -->|"routes tool calls"| node_mcp
node_mcp -.->|"calls tools"| node_mcp_servers
node_coordinator -.->|"observes runs"| node_forgex_observer
node_forgex_observer -->|"stores artifacts"| node_forgex_store
node_forgex_cli -->|"checks tool policy"| node_forgex_policy
node_forgex_api -->|"reads run data"| node_forgex_store
node_forgex_cli -->|"indexes run data"| node_forgex_store
node_forgex_stop -->|"records decisions"| node_forgex_store

click node_dashboard "https://github.com/castwell-4439/forge/blob/main/web/src/App.tsx"
click node_registry "https://github.com/castwell-4439/forge/blob/main/internal/registry/registry.go"
click node_scheduler "https://github.com/castwell-4439/forge/blob/main/internal/scheduler/scheduler.go"
click node_coordinator "https://github.com/castwell-4439/forge/blob/main/internal/coordinator/coordinator.go"
click node_hitl "https://github.com/castwell-4439/forge/blob/main/internal/hitl/manager.go"
click node_events "https://github.com/castwell-4439/forge/blob/main/internal/event/store.go"
click node_saga "https://github.com/castwell-4439/forge/blob/main/internal/saga/compensator.go"
click node_worker_mgr "https://github.com/castwell-4439/forge/blob/main/internal/coordinator/worker_manager.go"
click node_worker_runtime "https://github.com/castwell-4439/forge/blob/main/internal/worker/worker.go"
click node_builtin_workers "https://github.com/castwell-4439/forge/blob/main/internal/workers/ai/worker.go"
click node_agent "https://github.com/castwell-4439/forge/blob/main/internal/agent/harness/loop.go"
click node_planning "https://github.com/castwell-4439/forge/blob/main/internal/agent/planning/planner.go"
click node_rag "https://github.com/castwell-4439/forge/blob/main/internal/agent/rag/hybrid.go"
click node_mcp "https://github.com/castwell-4439/forge/blob/main/internal/agent/mcp/manager.go"
click node_guardrails "https://github.com/castwell-4439/forge/blob/main/internal/agent/guardrails/injection.go"
click node_storage "https://github.com/castwell-4439/forge/blob/main/internal/storage/interface.go"
click node_bus "https://github.com/castwell-4439/forge/blob/main/internal/bus/nats.go"
click node_discovery "https://github.com/castwell-4439/forge/blob/main/internal/discovery/etcd.go"
click node_cdc "https://github.com/castwell-4439/forge/blob/main/internal/cdc/postgres.go"
click node_observability "https://github.com/castwell-4439/forge/blob/main/internal/observability/metrics.go"
click node_sdk "https://github.com/castwell-4439/forge/blob/main/sdk/go/worker.go"
click node_forgex_observer "https://github.com/castwell-4439/forge/blob/main/internal/forgex/runtime/file_observer.go"
click node_forgex_policy "https://github.com/castwell-4439/forge/blob/main/internal/forgex/policy/engine.go"
click node_forgex_stop "https://github.com/castwell-4439/forge/blob/main/internal/forgex/stop/engine.go"
click node_forgex_api "https://github.com/castwell-4439/forge/blob/main/internal/forgex/productapi/server.go"
click node_forgex_store "https://github.com/castwell-4439/forge/blob/main/internal/forgex/storage/store.go"
click node_forgex_cli "https://github.com/castwell-4439/forge/blob/main/cmd/forgex/main.go"

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_registry,node_scheduler,node_coordinator,node_hitl,node_events,node_saga,node_user toneBlue
class node_worker_mgr,node_worker_runtime,node_builtin_workers,node_sdk,node_postgres,node_etcd toneAmber
class node_storage,node_bus,node_discovery,node_cdc,node_observability,node_mcp_servers toneMint
class node_agent,node_planning,node_rag,node_mcp,node_guardrails toneRose
class node_forgex_observer,node_forgex_policy,node_forgex_stop,node_forgex_api,node_forgex_store,node_forgex_cli,node_nats toneIndigo
class node_dashboard toneTeal
```

## Components

### Workflow runtime

- [YAML registry](https://github.com/castwell-4439/forge/blob/main/internal/registry/registry.go): `internal/registry/registry.go`
- [Workflow scheduler](https://github.com/castwell-4439/forge/blob/main/internal/scheduler/scheduler.go): `internal/scheduler/scheduler.go`
- [DAG coordinator](https://github.com/castwell-4439/forge/blob/main/internal/coordinator/coordinator.go): `internal/coordinator/coordinator.go`
- [Approval manager](https://github.com/castwell-4439/forge/blob/main/internal/hitl/manager.go): `internal/hitl/manager.go`
- [Event store](https://github.com/castwell-4439/forge/blob/main/internal/event/store.go): `internal/event/store.go`
- [Saga compensation](https://github.com/castwell-4439/forge/blob/main/internal/saga/compensator.go): `internal/saga/compensator.go`

### Worker execution

- [Worker manager](https://github.com/castwell-4439/forge/blob/main/internal/coordinator/worker_manager.go): `internal/coordinator/worker_manager.go`
- [Worker runtime](https://github.com/castwell-4439/forge/blob/main/internal/worker/worker.go): `internal/worker/worker.go`
- [Built-in workers](https://github.com/castwell-4439/forge/blob/main/internal/workers/ai/worker.go): `internal/workers/ai/worker.go`
- [Worker SDKs](https://github.com/castwell-4439/forge/blob/main/sdk/go/worker.go): `sdk/go/worker.go`

### Platform services

- [Metadata storage](https://github.com/castwell-4439/forge/blob/main/internal/storage/interface.go): `internal/storage/interface.go`
- [Message bus](https://github.com/castwell-4439/forge/blob/main/internal/bus/nats.go): `internal/bus/nats.go`
- [Service discovery](https://github.com/castwell-4439/forge/blob/main/internal/discovery/etcd.go): `internal/discovery/etcd.go`
- [Change capture](https://github.com/castwell-4439/forge/blob/main/internal/cdc/postgres.go): `internal/cdc/postgres.go`
- [Observability](https://github.com/castwell-4439/forge/blob/main/internal/observability/metrics.go): `internal/observability/metrics.go`

### Agent framework

- [Agent runtime](https://github.com/castwell-4439/forge/blob/main/internal/agent/harness/loop.go): `internal/agent/harness/loop.go`
- [Agent planning](https://github.com/castwell-4439/forge/blob/main/internal/agent/planning/planner.go): `internal/agent/planning/planner.go`
- [Hybrid retrieval](https://github.com/castwell-4439/forge/blob/main/internal/agent/rag/hybrid.go): `internal/agent/rag/hybrid.go`
- [MCP manager](https://github.com/castwell-4439/forge/blob/main/internal/agent/mcp/manager.go): `internal/agent/mcp/manager.go`
- [Agent guardrails](https://github.com/castwell-4439/forge/blob/main/internal/agent/guardrails/injection.go): `internal/agent/guardrails/injection.go`

### ForgeX control plane

- [Runtime observer](https://github.com/castwell-4439/forge/blob/main/internal/forgex/runtime/file_observer.go): `internal/forgex/runtime/file_observer.go`
- [Tool policy](https://github.com/castwell-4439/forge/blob/main/internal/forgex/policy/engine.go): `internal/forgex/policy/engine.go`
- [Stop decisions](https://github.com/castwell-4439/forge/blob/main/internal/forgex/stop/engine.go): `internal/forgex/stop/engine.go`
- [ForgeX API](https://github.com/castwell-4439/forge/blob/main/internal/forgex/productapi/server.go): `internal/forgex/productapi/server.go`
- [Run artifacts](https://github.com/castwell-4439/forge/blob/main/internal/forgex/storage/store.go): `internal/forgex/storage/store.go`
- [ForgeX CLI](https://github.com/castwell-4439/forge/blob/main/cmd/forgex/main.go): `cmd/forgex/main.go`

### Other components

- **Workflow user**
- [Admin dashboard](https://github.com/castwell-4439/forge/blob/main/web/src/App.tsx): `web/src/App.tsx`
- **PostgreSQL**
- **etcd**
- **NATS**
- **MCP servers**

## Connections

- Workflow user → YAML registry: defines workflow
- Workflow user → Admin dashboard: views operations
- Admin dashboard → DAG coordinator: submits tasks
- YAML registry → DAG coordinator: compiles DAG
- Workflow scheduler → DAG coordinator: triggers runs
- DAG coordinator → Worker manager: selects workers
- Worker manager → Service discovery: tracks workers
- DAG coordinator → Worker runtime: dispatches tasks
- Worker runtime → Built-in workers: runs handlers
- Worker SDKs → Worker runtime: implements workers
- DAG coordinator → Approval manager: requests approval
- DAG coordinator → Event store: records events
- Saga compensation → Event store: reads run events
- DAG coordinator → Metadata storage: persists state
- DAG coordinator → Message bus: publishes tasks
- Message bus → NATS: transfers messages
- Service discovery → etcd: registers services
- Change capture → PostgreSQL: streams WAL changes
- DAG coordinator → Observability: reports telemetry
- Agent runtime → Agent planning: requests plans
- Agent runtime → Hybrid retrieval: retrieves context
- Agent runtime → Agent guardrails: checks inputs
- Agent runtime → MCP manager: routes tool calls
- MCP manager → MCP servers: calls tools
- DAG coordinator → Runtime observer: observes runs
- Runtime observer → Run artifacts: stores artifacts
- ForgeX CLI → Tool policy: checks tool policy
- ForgeX API → Run artifacts: reads run data
- ForgeX CLI → Run artifacts: indexes run data
- Stop decisions → Run artifacts: records decisions