# earendil-works/absurd architecture

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

- Interactive diagram: https://gitdiagram.com/earendil-works/absurd
- Repository: https://github.com/earendil-works/absurd

## Overview

Absurd is a PostgreSQL-backed durable workflow system, with language SDKs for defining and running tasks and Habitat as an operations dashboard. The documented workflow is task dispatch to a queue, worker execution of checkpointed steps, and persistence of state for retries, suspension, and event waits. Habitat’s Go service exposes database-backed APIs and serves a browser UI for tasks, runs, queues, events, and metrics. The SQL implementation and several frontend/API modules are not in the supplied tree or excerpts, so those internals are not expanded here.

Main entry points: [`habitat/ui/src/App.tsx`](https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/App.tsx) (UI router and layout), [`habitat/internal/server/server.go`](https://github.com/earendil-works/absurd/blob/main/habitat/internal/server/server.go) (HTTP server and routes), [`habitat/cmd/habitat/main.go`](https://github.com/earendil-works/absurd/blob/main/habitat/cmd/habitat/main.go) (Habitat entrypoint), [`habitat/internal/server/handlers.go`](https://github.com/earendil-works/absurd/blob/main/habitat/internal/server/handlers.go) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["Workflow SDKs"]
  node_ts_sdk["TypeScript SDK<br/>[index.ts]"]
  node_py_sdk["Python SDK<br/>[__init__.py]"]
  node_go_sdk["Go SDK"]
  node_go_worker["Go worker<br/>[worker.go]"]
end

subgraph group_backend["Habitat service"]
  node_habitat_main["Habitat entrypoint<br/>[main.go]"]
  node_config["Runtime configuration<br/>[config.go]"]
  node_http_server["HTTP server and routes<br/>[server.go]"]
  node_api_handlers["Dashboard API<br/>[handlers.go]"]
  node_static_assets["Static asset serving<br/>[static.go]"]
end

subgraph group_frontend["Habitat UI"]
  node_app["UI router and layout<br/>[App.tsx]"]
  node_overview["Overview view<br/>[Overview.tsx]"]
  node_tasks["Task runs view<br/>[Tasks.tsx]"]
  node_task_history["Task history view<br/>[TaskRuns.tsx]"]
  node_queues["Queues view<br/>[Queues.tsx]"]
  node_events["Event log view<br/>[EventLog.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

node_developer(("Application developer"))
node_postgres[("PostgreSQL")]
node_habitat_user(("Dashboard user"))
node_browser(("Browser UI"))

node_developer -->|"defines workflows"| node_ts_sdk
node_developer -->|"installs SDK"| node_py_sdk
node_developer -->|"installs SDK"| node_go_sdk
node_ts_sdk -->|"queries workflow state"| node_postgres
node_go_worker -->|"claims task runs"| node_postgres
node_go_sdk -.->|"runs workers"| node_go_worker
node_habitat_main -->|"loads arguments"| node_config
node_habitat_main -->|"starts service"| node_http_server
node_habitat_main -->|"opens connection"| node_postgres
node_http_server -->|"routes API requests"| node_api_handlers
node_http_server -->|"serves static files"| node_static_assets
node_api_handlers -->|"queries dashboard data"| node_postgres
node_browser -->|"requests dashboard"| node_http_server
node_browser -->|"loads interface"| node_app
node_app -->|"routes to"| node_overview
node_app -->|"routes to"| node_tasks
node_app -->|"routes to"| node_task_history
node_app -->|"routes to"| node_queues
node_app -->|"routes to"| node_events
node_tasks -->|"fetches task details"| node_api_client
node_api_client -.->|"calls dashboard API"| node_api_handlers

click node_ts_sdk "https://github.com/earendil-works/absurd/blob/main/sdks/typescript/src/index.ts"
click node_py_sdk "https://github.com/earendil-works/absurd/blob/main/sdks/python/src/absurd_sdk/__init__.py"
click node_go_sdk "https://github.com/earendil-works/absurd/tree/main/sdks/go/absurd"
click node_go_worker "https://github.com/earendil-works/absurd/blob/main/sdks/go/absurd/worker.go"
click node_habitat_main "https://github.com/earendil-works/absurd/blob/main/habitat/cmd/habitat/main.go"
click node_config "https://github.com/earendil-works/absurd/blob/main/habitat/internal/config/config.go"
click node_http_server "https://github.com/earendil-works/absurd/blob/main/habitat/internal/server/server.go"
click node_api_handlers "https://github.com/earendil-works/absurd/blob/main/habitat/internal/server/handlers.go"
click node_static_assets "https://github.com/earendil-works/absurd/blob/main/habitat/internal/web/static.go"
click node_app "https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/App.tsx"
click node_overview "https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/views/Overview.tsx"
click node_tasks "https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/views/Tasks.tsx"
click node_task_history "https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/views/TaskRuns.tsx"
click node_queues "https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/views/Queues.tsx"
click node_events "https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/views/EventLog.tsx"
click node_api_client "https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/lib/api.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_ts_sdk,node_py_sdk,node_go_sdk,node_go_worker,node_habitat_user,node_browser toneBlue
class node_habitat_main,node_config,node_http_server,node_api_handlers,node_static_assets,node_postgres toneAmber
class node_app,node_overview,node_tasks,node_task_history,node_queues,node_events,node_api_client toneMint
class node_developer toneIndigo
```

## Components

### Workflow SDKs

- [TypeScript SDK](https://github.com/earendil-works/absurd/blob/main/sdks/typescript/src/index.ts): `sdks/typescript/src/index.ts`
- [Python SDK](https://github.com/earendil-works/absurd/blob/main/sdks/python/src/absurd_sdk/__init__.py): `sdks/python/src/absurd_sdk/__init__.py`
- [Go SDK](https://github.com/earendil-works/absurd/tree/main/sdks/go/absurd): `sdks/go/absurd`
- [Go worker](https://github.com/earendil-works/absurd/blob/main/sdks/go/absurd/worker.go): `sdks/go/absurd/worker.go`

### Habitat service

- [Habitat entrypoint](https://github.com/earendil-works/absurd/blob/main/habitat/cmd/habitat/main.go): `habitat/cmd/habitat/main.go`
- [Runtime configuration](https://github.com/earendil-works/absurd/blob/main/habitat/internal/config/config.go): `habitat/internal/config/config.go`
- [HTTP server and routes](https://github.com/earendil-works/absurd/blob/main/habitat/internal/server/server.go): `habitat/internal/server/server.go`
- [Dashboard API](https://github.com/earendil-works/absurd/blob/main/habitat/internal/server/handlers.go): `habitat/internal/server/handlers.go`
- [Static asset serving](https://github.com/earendil-works/absurd/blob/main/habitat/internal/web/static.go): `habitat/internal/web/static.go`

### Habitat UI

- [UI router and layout](https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/App.tsx): `habitat/ui/src/App.tsx`
- [Overview view](https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/views/Overview.tsx): `habitat/ui/src/views/Overview.tsx`
- [Task runs view](https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/views/Tasks.tsx): `habitat/ui/src/views/Tasks.tsx`
- [Task history view](https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/views/TaskRuns.tsx): `habitat/ui/src/views/TaskRuns.tsx`
- [Queues view](https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/views/Queues.tsx): `habitat/ui/src/views/Queues.tsx`
- [Event log view](https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/views/EventLog.tsx): `habitat/ui/src/views/EventLog.tsx`
- [API client](https://github.com/earendil-works/absurd/blob/main/habitat/ui/src/lib/api.ts): `habitat/ui/src/lib/api.ts`

### Other components

- **Application developer**
- **PostgreSQL**
- **Dashboard user**
- **Browser UI**

## Connections

- Application developer → TypeScript SDK: defines workflows (evidence: `README.md`)
- Application developer → Python SDK: installs SDK (evidence: `README.md`)
- Application developer → Go SDK: installs SDK (evidence: `README.md`)
- TypeScript SDK → PostgreSQL: queries workflow state (evidence: `sdks/typescript/src/index.ts`)
- Go worker → PostgreSQL: claims task runs (evidence: `sdks/go/absurd/worker.go`)
- Go SDK → Go worker: runs workers
- Habitat entrypoint → Runtime configuration: loads arguments (evidence: `habitat/cmd/habitat/main.go`)
- Habitat entrypoint → HTTP server and routes: starts service (evidence: `habitat/cmd/habitat/main.go`)
- Habitat entrypoint → PostgreSQL: opens connection (evidence: `habitat/cmd/habitat/main.go`)
- HTTP server and routes → Dashboard API: routes API requests (evidence: `habitat/internal/server/server.go`)
- HTTP server and routes → Static asset serving: serves static files (evidence: `habitat/internal/server/server.go`)
- Dashboard API → PostgreSQL: queries dashboard data (evidence: `habitat/internal/server/handlers.go`)
- Browser UI → HTTP server and routes: requests dashboard (evidence: `habitat/internal/server/server.go`)
- Browser UI → UI router and layout: loads interface (evidence: `README.md`)
- UI router and layout → Overview view: routes to (evidence: `habitat/ui/src/App.tsx`)
- UI router and layout → Task runs view: routes to (evidence: `habitat/ui/src/App.tsx`)
- UI router and layout → Task history view: routes to (evidence: `habitat/ui/src/App.tsx`)
- UI router and layout → Queues view: routes to (evidence: `habitat/ui/src/App.tsx`)
- UI router and layout → Event log view: routes to (evidence: `habitat/ui/src/App.tsx`)
- Task runs view → API client: fetches task details (evidence: `habitat/ui/src/views/Tasks.tsx`)
- API client → Dashboard API: calls dashboard API
