How castwell-4439/forge works
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: coordinator.go DAG coordinator · loop.go Agent runtime · store.go Run artifacts · worker.go Worker runtime
Components 32
Workflow runtime
- YAML registry
internal/registry/registry.go - Workflow scheduler
internal/scheduler/scheduler.go - DAG coordinator
internal/coordinator/coordinator.go - Approval manager
internal/hitl/manager.go - Event store
internal/event/store.go - Saga compensation
internal/saga/compensator.go
Worker execution
- Worker manager
internal/coordinator/worker_manager.go - Worker runtime
internal/worker/worker.go - Built-in workers
internal/workers/ai/worker.go - Worker SDKs
sdk/go/worker.go
Platform services
- Metadata storage
internal/storage/interface.go - Message bus
internal/bus/nats.go - Service discovery
internal/discovery/etcd.go - Change capture
internal/cdc/postgres.go - Observability
internal/observability/metrics.go
Agent framework
- Agent runtime
internal/agent/harness/loop.go - Agent planning
internal/agent/planning/planner.go - Hybrid retrieval
internal/agent/rag/hybrid.go - MCP manager
internal/agent/mcp/manager.go - Agent guardrails
internal/agent/guardrails/injection.go
ForgeX control plane
- Runtime observer
internal/forgex/runtime/file_observer.go - Tool policy
internal/forgex/policy/engine.go - Stop decisions
internal/forgex/stop/engine.go - ForgeX API
internal/forgex/productapi/server.go - Run artifacts
internal/forgex/storage/store.go - ForgeX CLI
cmd/forgex/main.go
Other components
- Workflow user
- Admin dashboard
web/src/App.tsx - PostgreSQL
- etcd
- NATS
- MCP servers
Connections 30
- 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