# dimfeld/ergo architecture

> Architecture diagram of the GitHub repository dimfeld/ergo, 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/dimfeld/ergo
- Repository: https://github.com/dimfeld/ergo

## Overview

Ergo is a low-code automation service: users configure tasks, triggers, inputs, and actions in the Svelte UI; incoming or scheduled events are queued, applied to task logic, and dispatched to actions, with execution logs and optional notifications. The backend also supports JavaScript, state-machine and DAG-style task logic, templates, HTTP and local-command actions, and account-linked actions. Paths and relationships are based on the supplied tree, README, and sampled excerpts; unsampled subsystem wiring is shown only where documented or evident from the runtime entry points.

Main entry points: [`tasks/lib.rs`](https://github.com/dimfeld/ergo/blob/master/tasks/lib.rs) (Apply task input), [`api/server.rs`](https://github.com/dimfeld/ergo/blob/master/api/server.rs) (HTTP server), [`tasks/actions/execute.rs`](https://github.com/dimfeld/ergo/blob/master/tasks/actions/execute.rs) (Action executors), [`tasks/inputs/queue.rs`](https://github.com/dimfeld/ergo/blob/master/tasks/inputs/queue.rs) (Input queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Configuration UI"]
  node_webui["Task editor<br/>[+page.svelte]"]
  node_editors["Workflow editors<br/>[DataFlow.svelte]"]
  node_webapi["API client<br/>[api.ts]"]
end

subgraph group_api["API and triggers"]
  node_server["HTTP server<br/>[server.rs]"]
  node_auth["Authentication<br/>[lib.rs]"]
  node_taskroutes["Task routes<br/>[tasks.rs]"]
  node_inputsroute["Input routes<br/>[inputs.rs]"]
end

subgraph group_execution["Task execution"]
  node_periodic["Periodic triggers<br/>[periodic.rs]"]
  node_inputqueue["Input queue<br/>[queue.rs]"]
  node_applyinput["Apply task input<br/>[lib.rs]"]
  node_statemachine["State machines<br/>[state_machine.rs]"]
  node_dataflow["DAG workflows<br/>[run.rs]"]
  node_actionqueue["Action queue<br/>[queue.rs]"]
  node_actiondispatch["Action dispatch<br/>[dequeue.rs]"]
  node_executors["Action executors<br/>[execute.rs]"]
end

subgraph group_runtime["Runtime services"]
  node_jsexec["JavaScript runtime<br/>[runtime.rs]"]
  node_jsengine["V8 engine<br/>[lib.rs]"]
  node_postgres[("PostgreSQL<br/>[pool.rs]")]
  node_redis[("Redis<br/>[redis.rs]")]
  node_notifications["Notifications<br/>[lib.rs]"]
end

node_operator(("Operator"))
node_caller(("Event caller"))
node_external(("HTTP services"))

node_operator -->|"configures"| node_webui
node_webui -->|"edits workflows"| node_editors
node_webui -->|"requests data"| node_webapi
node_webapi -->|"calls API"| node_server
node_caller -->|"sends event"| node_server
node_server -->|"authenticates"| node_auth
node_server -->|"dispatches"| node_taskroutes
node_server -->|"dispatches"| node_inputsroute
node_taskroutes -->|"reads/writes"| node_postgres
node_inputsroute -->|"enqueues input"| node_inputqueue
node_periodic -->|"enqueues scheduled"| node_inputqueue
node_inputqueue -->|"stores jobs"| node_redis
node_inputqueue -->|"dequeues input"| node_applyinput
node_applyinput -->|"loads and logs"| node_postgres
node_applyinput -->|"applies trigger"| node_statemachine
node_applyinput -->|"runs workflow"| node_dataflow
node_applyinput -->|"enqueues actions"| node_actionqueue
node_actionqueue -->|"stores jobs"| node_redis
node_actionqueue -->|"dequeues actions"| node_actiondispatch
node_actiondispatch -->|"dispatches"| node_executors
node_executors -->|"runs scripts"| node_jsexec
node_jsexec -->|"evaluates JavaScript"| node_jsengine
node_executors -.->|"calls HTTP"| node_external
node_executors -->|"records results"| node_postgres
node_applyinput -->|"notifies outcomes"| node_notifications
node_notifications -.->|"sends webhook"| node_external

click node_webui "https://github.com/dimfeld/ergo/blob/master/web/src/routes/tasks/%2Bpage.svelte"
click node_editors "https://github.com/dimfeld/ergo/blob/master/web/src/lib/editors/dataflow/DataFlow.svelte"
click node_webapi "https://github.com/dimfeld/ergo/blob/master/web/src/lib/api.ts"
click node_server "https://github.com/dimfeld/ergo/blob/master/api/server.rs"
click node_auth "https://github.com/dimfeld/ergo/blob/master/auth/lib.rs"
click node_taskroutes "https://github.com/dimfeld/ergo/blob/master/api/routes/tasks.rs"
click node_inputsroute "https://github.com/dimfeld/ergo/blob/master/api/routes/inputs.rs"
click node_periodic "https://github.com/dimfeld/ergo/blob/master/tasks/periodic.rs"
click node_inputqueue "https://github.com/dimfeld/ergo/blob/master/tasks/inputs/queue.rs"
click node_applyinput "https://github.com/dimfeld/ergo/blob/master/tasks/lib.rs"
click node_statemachine "https://github.com/dimfeld/ergo/blob/master/tasks/state_machine.rs"
click node_dataflow "https://github.com/dimfeld/ergo/blob/master/tasks/dataflow/run.rs"
click node_actionqueue "https://github.com/dimfeld/ergo/blob/master/tasks/actions/queue.rs"
click node_actiondispatch "https://github.com/dimfeld/ergo/blob/master/tasks/actions/dequeue.rs"
click node_executors "https://github.com/dimfeld/ergo/blob/master/tasks/actions/execute.rs"
click node_jsexec "https://github.com/dimfeld/ergo/blob/master/tasks/scripting/runtime.rs"
click node_jsengine "https://github.com/dimfeld/ergo/blob/master/js/lib.rs"
click node_postgres "https://github.com/dimfeld/ergo/blob/master/database/pool.rs"
click node_redis "https://github.com/dimfeld/ergo/blob/master/database/redis.rs"
click node_notifications "https://github.com/dimfeld/ergo/blob/master/notifications/lib.rs"

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_webui,node_editors,node_webapi toneBlue
class node_server,node_auth,node_taskroutes,node_inputsroute toneAmber
class node_periodic,node_inputqueue,node_applyinput,node_statemachine,node_dataflow,node_actionqueue,node_actiondispatch,node_executors toneMint
class node_jsexec,node_jsengine,node_postgres,node_redis,node_notifications toneRose
class node_operator,node_caller,node_external toneIndigo
```

## Components

### Configuration UI

- [Task editor](https://github.com/dimfeld/ergo/blob/master/web/src/routes/tasks/%2Bpage.svelte): `web/src/routes/tasks/+page.svelte`
- [Workflow editors](https://github.com/dimfeld/ergo/blob/master/web/src/lib/editors/dataflow/DataFlow.svelte): `web/src/lib/editors/dataflow/DataFlow.svelte`
- [API client](https://github.com/dimfeld/ergo/blob/master/web/src/lib/api.ts): `web/src/lib/api.ts`

### API and triggers

- [HTTP server](https://github.com/dimfeld/ergo/blob/master/api/server.rs): `api/server.rs`
- [Authentication](https://github.com/dimfeld/ergo/blob/master/auth/lib.rs): `auth/lib.rs`
- [Task routes](https://github.com/dimfeld/ergo/blob/master/api/routes/tasks.rs): `api/routes/tasks.rs`
- [Input routes](https://github.com/dimfeld/ergo/blob/master/api/routes/inputs.rs): `api/routes/inputs.rs`

### Task execution

- [Periodic triggers](https://github.com/dimfeld/ergo/blob/master/tasks/periodic.rs): `tasks/periodic.rs`
- [Input queue](https://github.com/dimfeld/ergo/blob/master/tasks/inputs/queue.rs): `tasks/inputs/queue.rs`
- [Apply task input](https://github.com/dimfeld/ergo/blob/master/tasks/lib.rs): `tasks/lib.rs`
- [State machines](https://github.com/dimfeld/ergo/blob/master/tasks/state_machine.rs): `tasks/state_machine.rs`
- [DAG workflows](https://github.com/dimfeld/ergo/blob/master/tasks/dataflow/run.rs): `tasks/dataflow/run.rs`
- [Action queue](https://github.com/dimfeld/ergo/blob/master/tasks/actions/queue.rs): `tasks/actions/queue.rs`
- [Action dispatch](https://github.com/dimfeld/ergo/blob/master/tasks/actions/dequeue.rs): `tasks/actions/dequeue.rs`
- [Action executors](https://github.com/dimfeld/ergo/blob/master/tasks/actions/execute.rs): `tasks/actions/execute.rs`

### Runtime services

- [JavaScript runtime](https://github.com/dimfeld/ergo/blob/master/tasks/scripting/runtime.rs): `tasks/scripting/runtime.rs`
- [V8 engine](https://github.com/dimfeld/ergo/blob/master/js/lib.rs): `js/lib.rs`
- [PostgreSQL](https://github.com/dimfeld/ergo/blob/master/database/pool.rs): `database/pool.rs`
- [Redis](https://github.com/dimfeld/ergo/blob/master/database/redis.rs): `database/redis.rs`
- [Notifications](https://github.com/dimfeld/ergo/blob/master/notifications/lib.rs): `notifications/lib.rs`

### Other components

- **Operator**
- **Event caller**
- **HTTP services**

## Connections

- Operator → Task editor: configures
- Task editor → Workflow editors: edits workflows
- Task editor → API client: requests data
- API client → HTTP server: calls API
- Event caller → HTTP server: sends event
- HTTP server → Authentication: authenticates
- HTTP server → Task routes: dispatches
- HTTP server → Input routes: dispatches
- Task routes → PostgreSQL: reads/writes
- Input routes → Input queue: enqueues input
- Periodic triggers → Input queue: enqueues scheduled
- Input queue → Redis: stores jobs
- Input queue → Apply task input: dequeues input
- Apply task input → PostgreSQL: loads and logs
- Apply task input → State machines: applies trigger
- Apply task input → DAG workflows: runs workflow
- Apply task input → Action queue: enqueues actions
- Action queue → Redis: stores jobs
- Action queue → Action dispatch: dequeues actions
- Action dispatch → Action executors: dispatches
- Action executors → JavaScript runtime: runs scripts
- JavaScript runtime → V8 engine: evaluates JavaScript
- Action executors → HTTP services: calls HTTP
- Action executors → PostgreSQL: records results
- Apply task input → Notifications: notifies outcomes
- Notifications → HTTP services: sends webhook