# andiswarm/go-taskengine architecture

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

## Overview

Go-TaskEngine is a Redis-backed Go task execution engine, not a web service. Producers create and enqueue immediate or delayed task messages; the server claims ready work, dispatches it to task-type handlers, and records completion, retry, or archive transitions. The Redis store also supports dead-letter replay and cleanup; server maintenance handles lease renewal and expired-task recovery. Examples demonstrate simulated image-processing and C2PA signing workflows. Edges reflect the README and sampled implementations; some example wiring and unsampled store operations are represented only where documented.

Main entry points: [`server/server.go`](https://github.com/andiswarm/go-taskengine/blob/main/server/server.go) (Server Scheduler), [`client/client.go`](https://github.com/andiswarm/go-taskengine/blob/main/client/client.go) (Client Enqueue), [`server/handler_mux.go`](https://github.com/andiswarm/go-taskengine/blob/main/server/handler_mux.go) (Handler Router), [`examples/image-processing/cmd/worker/main.go`](https://github.com/andiswarm/go-taskengine/blob/main/examples/image-processing/cmd/worker/main.go) (Image Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Task APIs"]
  node_client["Client Enqueue<br/>[client.go]"]
  node_message["Task Message<br/>[model.go]"]
  node_storecontract["Storage Contract<br/>[storage.go]"]
end

subgraph group_engine["Worker Engine"]
  node_server["Server Scheduler<br/>[server.go]"]
  node_mux["Handler Router<br/>[handler_mux.go]"]
  node_timer["Timer Wheel<br/>[timer.go]"]
  node_limiter["Token Bucket<br/>[bucket.go]"]
end

subgraph group_persistence["Redis Persistence"]
  node_redisapi["Redis Store API<br/>[redisstore.go]"]
  node_redisstore["Redis State Machine<br/>[rdb.go]"]
  node_deadletters["Dead Letter Operations<br/>[storage.go]"]
end

subgraph group_examples["Example Workloads"]
  node_imageproducer["Image Producer<br/>[main.go]"]
  node_imagehandler["Image Handler<br/>[image.go]"]
  node_imageworker["Image Worker<br/>[main.go]"]
  node_c2paproducer["C2PA Producer<br/>[main.go]"]
  node_c2pahandler["C2PA Handler<br/>[signing.go]"]
  node_c2paworker["C2PA Worker<br/>[main.go]"]
end

node_producer(("Task Producer"))
node_workeractor(("Worker Operator"))
node_redis[("Redis")]

node_producer -->|"creates tasks"| node_client
node_client -->|"builds envelope"| node_message
node_client -->|"enqueues or schedules"| node_storecontract
node_server -->|"claims and transitions"| node_storecontract
node_server -->|"dispatches tasks"| node_mux
node_mux -.->|"routes by type"| node_imagehandler
node_mux -.->|"routes by type"| node_c2pahandler
node_server -->|"schedules wakeups"| node_timer
node_server -->|"acquires tokens"| node_limiter
node_storecontract -->|"implemented by"| node_redisapi
node_redisapi -->|"delegates to"| node_redisstore
node_redisstore -->|"reads and writes state"| node_redis
node_limiter -->|"updates token state"| node_redis
node_workeractor -.->|"starts worker"| node_imageworker
node_imageworker -->|"runs server"| node_server
node_imageworker -->|"registers handler"| node_mux
node_imageproducer -->|"enqueues task"| node_client
node_workeractor -.->|"starts worker"| node_c2paworker
node_c2paworker -->|"runs server"| node_server
node_c2paworker -->|"registers handler"| node_mux
node_c2paproducer -->|"enqueues task"| node_client
node_deadletters -->|"supports archive operations"| node_redisstore

click node_client "https://github.com/andiswarm/go-taskengine/blob/main/client/client.go"
click node_message "https://github.com/andiswarm/go-taskengine/blob/main/model/model.go"
click node_storecontract "https://github.com/andiswarm/go-taskengine/blob/main/storage/storage.go"
click node_server "https://github.com/andiswarm/go-taskengine/blob/main/server/server.go"
click node_mux "https://github.com/andiswarm/go-taskengine/blob/main/server/handler_mux.go"
click node_timer "https://github.com/andiswarm/go-taskengine/blob/main/internal/timer/timer.go"
click node_limiter "https://github.com/andiswarm/go-taskengine/blob/main/internal/limiter/bucket.go"
click node_redisapi "https://github.com/andiswarm/go-taskengine/blob/main/redisstore/redisstore.go"
click node_redisstore "https://github.com/andiswarm/go-taskengine/blob/main/internal/redisstore/rdb.go"
click node_deadletters "https://github.com/andiswarm/go-taskengine/blob/main/storage/storage.go"
click node_imageproducer "https://github.com/andiswarm/go-taskengine/blob/main/examples/image-processing/cmd/producer/main.go"
click node_imagehandler "https://github.com/andiswarm/go-taskengine/blob/main/examples/image-processing/image.go"
click node_imageworker "https://github.com/andiswarm/go-taskengine/blob/main/examples/image-processing/cmd/worker/main.go"
click node_c2paproducer "https://github.com/andiswarm/go-taskengine/blob/main/examples/c2pa-signing/cmd/producer/main.go"
click node_c2pahandler "https://github.com/andiswarm/go-taskengine/blob/main/examples/c2pa-signing/signing.go"
click node_c2paworker "https://github.com/andiswarm/go-taskengine/blob/main/examples/c2pa-signing/cmd/worker/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_client,node_message,node_storecontract toneBlue
class node_server,node_mux,node_timer,node_limiter,node_redis toneAmber
class node_redisapi,node_redisstore,node_deadletters toneMint
class node_imageproducer,node_imagehandler,node_imageworker,node_c2paproducer,node_c2pahandler,node_c2paworker,node_producer,node_workeractor toneRose
```

## Components

### Task APIs

- [Client Enqueue](https://github.com/andiswarm/go-taskengine/blob/main/client/client.go): `client/client.go`
- [Task Message](https://github.com/andiswarm/go-taskengine/blob/main/model/model.go): `model/model.go`
- [Storage Contract](https://github.com/andiswarm/go-taskengine/blob/main/storage/storage.go): `storage/storage.go`

### Worker Engine

- [Server Scheduler](https://github.com/andiswarm/go-taskengine/blob/main/server/server.go): `server/server.go`
- [Handler Router](https://github.com/andiswarm/go-taskengine/blob/main/server/handler_mux.go): `server/handler_mux.go`
- [Timer Wheel](https://github.com/andiswarm/go-taskengine/blob/main/internal/timer/timer.go): `internal/timer/timer.go`
- [Token Bucket](https://github.com/andiswarm/go-taskengine/blob/main/internal/limiter/bucket.go): `internal/limiter/bucket.go`

### Redis Persistence

- [Redis Store API](https://github.com/andiswarm/go-taskengine/blob/main/redisstore/redisstore.go): `redisstore/redisstore.go`
- [Redis State Machine](https://github.com/andiswarm/go-taskengine/blob/main/internal/redisstore/rdb.go): `internal/redisstore/rdb.go`
- [Dead Letter Operations](https://github.com/andiswarm/go-taskengine/blob/main/storage/storage.go): `storage/storage.go`

### Example Workloads

- [Image Producer](https://github.com/andiswarm/go-taskengine/blob/main/examples/image-processing/cmd/producer/main.go): `examples/image-processing/cmd/producer/main.go`
- [Image Handler](https://github.com/andiswarm/go-taskengine/blob/main/examples/image-processing/image.go): `examples/image-processing/image.go`
- [Image Worker](https://github.com/andiswarm/go-taskengine/blob/main/examples/image-processing/cmd/worker/main.go): `examples/image-processing/cmd/worker/main.go`
- [C2PA Producer](https://github.com/andiswarm/go-taskengine/blob/main/examples/c2pa-signing/cmd/producer/main.go): `examples/c2pa-signing/cmd/producer/main.go`
- [C2PA Handler](https://github.com/andiswarm/go-taskengine/blob/main/examples/c2pa-signing/signing.go): `examples/c2pa-signing/signing.go`
- [C2PA Worker](https://github.com/andiswarm/go-taskengine/blob/main/examples/c2pa-signing/cmd/worker/main.go): `examples/c2pa-signing/cmd/worker/main.go`

### Other components

- **Task Producer**
- **Worker Operator**
- **Redis**

## Connections

- Task Producer → Client Enqueue: creates tasks
- Client Enqueue → Task Message: builds envelope
- Client Enqueue → Storage Contract: enqueues or schedules
- Server Scheduler → Storage Contract: claims and transitions
- Server Scheduler → Handler Router: dispatches tasks
- Handler Router → Image Handler: routes by type
- Handler Router → C2PA Handler: routes by type
- Server Scheduler → Timer Wheel: schedules wakeups
- Server Scheduler → Token Bucket: acquires tokens
- Storage Contract → Redis Store API: implemented by
- Redis Store API → Redis State Machine: delegates to
- Redis State Machine → Redis: reads and writes state
- Token Bucket → Redis: updates token state
- Worker Operator → Image Worker: starts worker
- Image Worker → Server Scheduler: runs server
- Image Worker → Handler Router: registers handler
- Image Producer → Client Enqueue: enqueues task
- Worker Operator → C2PA Worker: starts worker
- C2PA Worker → Server Scheduler: runs server
- C2PA Worker → Handler Router: registers handler
- C2PA Producer → Client Enqueue: enqueues task
- Dead Letter Operations → Redis State Machine: supports archive operations