# work-frame/goflow architecture

> Architecture diagram of the GitHub repository work-frame/goflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/work-frame/goflow
- Repository: https://github.com/work-frame/goflow

## Overview

GoFlow is a background-job platform. Users submit and manage jobs through the CLI or web dashboard; the API persists them, relays queued work to Redis, and workers claim and execute jobs, recording completion, retry, or dead-letter outcomes. Separate capabilities include account/session management, live status events, metrics, and signed webhook delivery with recorded attempts. The README documents these product flows; sampled entry points and the source index support the service wiring, but several internal API and storage details were not sampled.

Main entry points: [`internal/api/api.go`](https://github.com/work-frame/goflow/blob/main/internal/api/api.go) (HTTP API), [`internal/worker/worker.go`](https://github.com/work-frame/goflow/blob/main/internal/worker/worker.go) (Worker pool), [`internal/webhook/deliver.go`](https://github.com/work-frame/goflow/blob/main/internal/webhook/deliver.go) (Webhook delivery), [`internal/database/jobs.go`](https://github.com/work-frame/goflow/blob/main/internal/database/jobs.go) (Job storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User access"]
  node_cli["CLI<br/>[cli.go]"]
  node_client["API client<br/>[client.go]"]
  node_dashboard["Dashboard<br/>[app.js]"]
  node_webhost["Web host<br/>[web.go]"]
end

subgraph group_service["API service"]
  node_api["HTTP API<br/>[api.go]"]
  node_auth["Accounts and sessions<br/>[auth.go]"]
end

subgraph group_lifecycle["Job lifecycle"]
  node_jobmodel["Job model<br/>[job.go]"]
  node_jobstore[("Job storage<br/>[jobs.go]")]
  node_outbox["Outbox relay<br/>[relay.go]"]
  node_queue["Redis queue<br/>[queue.go]"]
  node_workers["Worker pool<br/>[worker.go]"]
  node_workstore[("Work and leases<br/>[work.go]")]
end

subgraph group_live["Live operations"]
  node_events["Live events<br/>[publisher.go]"]
  node_eventhub["Event streams<br/>[hub.go]"]
  node_metrics["Metrics<br/>[metrics.go]"]
end

subgraph group_hooks["Webhook delivery"]
  node_secretstore[("Webhook secrets<br/>[webhooks.go]")]
  node_delivery["Webhook delivery<br/>[deliver.go]"]
  node_egress["Egress policy<br/>[policy.go]"]
end

node_user(("User"))
node_receiver["Webhook receiver<br/>[main.go]"]
node_postgres[("PostgreSQL")]
node_redis[("Redis")]

node_user -->|"runs"| node_cli
node_cli -->|"calls"| node_client
node_user -->|"uses"| node_dashboard
node_dashboard -->|"served by"| node_webhost
node_client -->|"HTTP requests"| node_api
node_webhost -.->|"accesses"| node_api
node_api -->|"handles auth"| node_auth
node_api -->|"manages jobs"| node_jobmodel
node_api -.->|"persists jobs"| node_jobstore
node_jobstore -->|"reads and writes"| node_postgres
node_api -->|"wakes relay"| node_outbox
node_outbox -->|"enqueues IDs"| node_queue
node_queue -->|"stores work"| node_redis
node_workers -->|"takes jobs"| node_queue
node_workers -->|"claims and records"| node_workstore
node_workstore -->|"leases jobs"| node_postgres
node_workers -->|"routes job types"| node_jobmodel
node_workers -->|"runs webhook jobs"| node_delivery
node_api -->|"publishes changes"| node_events
node_events -->|"feeds streams"| node_eventhub
node_api -->|"exposes metrics"| node_metrics
node_delivery -->|"checks destinations"| node_egress
node_delivery -->|"uses signing secrets"| node_secretstore
node_delivery -->|"sends signed POST"| node_receiver
node_api -->|"rotates secrets"| node_secretstore
node_api -->|"lists attempts"| node_jobstore
node_secretstore -->|"stores encrypted data"| node_postgres

click node_cli "https://github.com/work-frame/goflow/blob/main/internal/cli/cli.go"
click node_client "https://github.com/work-frame/goflow/blob/main/internal/client/client.go"
click node_dashboard "https://github.com/work-frame/goflow/blob/main/internal/web/static/app.js"
click node_webhost "https://github.com/work-frame/goflow/blob/main/internal/web/web.go"
click node_api "https://github.com/work-frame/goflow/blob/main/internal/api/api.go"
click node_auth "https://github.com/work-frame/goflow/blob/main/internal/api/auth.go"
click node_jobmodel "https://github.com/work-frame/goflow/blob/main/internal/job/job.go"
click node_jobstore "https://github.com/work-frame/goflow/blob/main/internal/database/jobs.go"
click node_outbox "https://github.com/work-frame/goflow/blob/main/internal/relay/relay.go"
click node_queue "https://github.com/work-frame/goflow/blob/main/internal/queue/queue.go"
click node_workers "https://github.com/work-frame/goflow/blob/main/internal/worker/worker.go"
click node_workstore "https://github.com/work-frame/goflow/blob/main/internal/database/work.go"
click node_events "https://github.com/work-frame/goflow/blob/main/internal/events/publisher.go"
click node_eventhub "https://github.com/work-frame/goflow/blob/main/internal/events/hub.go"
click node_metrics "https://github.com/work-frame/goflow/blob/main/internal/metrics/metrics.go"
click node_secretstore "https://github.com/work-frame/goflow/blob/main/internal/database/webhooks.go"
click node_delivery "https://github.com/work-frame/goflow/blob/main/internal/webhook/deliver.go"
click node_egress "https://github.com/work-frame/goflow/blob/main/internal/egress/policy.go"
click node_receiver "https://github.com/work-frame/goflow/blob/main/cmd/receiver/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_cli,node_client,node_dashboard,node_webhost,node_user toneBlue
class node_api,node_auth,node_postgres,node_redis toneAmber
class node_jobmodel,node_jobstore,node_outbox,node_queue,node_workers,node_workstore,node_receiver toneMint
class node_events,node_eventhub,node_metrics toneRose
class node_secretstore,node_delivery,node_egress toneIndigo
```

## Components

### User access

- [CLI](https://github.com/work-frame/goflow/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [API client](https://github.com/work-frame/goflow/blob/main/internal/client/client.go): `internal/client/client.go`
- [Dashboard](https://github.com/work-frame/goflow/blob/main/internal/web/static/app.js): `internal/web/static/app.js`
- [Web host](https://github.com/work-frame/goflow/blob/main/internal/web/web.go): `internal/web/web.go`

### API service

- [HTTP API](https://github.com/work-frame/goflow/blob/main/internal/api/api.go): `internal/api/api.go`
- [Accounts and sessions](https://github.com/work-frame/goflow/blob/main/internal/api/auth.go): `internal/api/auth.go`

### Job lifecycle

- [Job model](https://github.com/work-frame/goflow/blob/main/internal/job/job.go): `internal/job/job.go`
- [Job storage](https://github.com/work-frame/goflow/blob/main/internal/database/jobs.go): `internal/database/jobs.go`
- [Outbox relay](https://github.com/work-frame/goflow/blob/main/internal/relay/relay.go): `internal/relay/relay.go`
- [Redis queue](https://github.com/work-frame/goflow/blob/main/internal/queue/queue.go): `internal/queue/queue.go`
- [Worker pool](https://github.com/work-frame/goflow/blob/main/internal/worker/worker.go): `internal/worker/worker.go`
- [Work and leases](https://github.com/work-frame/goflow/blob/main/internal/database/work.go): `internal/database/work.go`

### Live operations

- [Live events](https://github.com/work-frame/goflow/blob/main/internal/events/publisher.go): `internal/events/publisher.go`
- [Event streams](https://github.com/work-frame/goflow/blob/main/internal/events/hub.go): `internal/events/hub.go`
- [Metrics](https://github.com/work-frame/goflow/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`

### Webhook delivery

- [Webhook secrets](https://github.com/work-frame/goflow/blob/main/internal/database/webhooks.go): `internal/database/webhooks.go`
- [Webhook delivery](https://github.com/work-frame/goflow/blob/main/internal/webhook/deliver.go): `internal/webhook/deliver.go`
- [Egress policy](https://github.com/work-frame/goflow/blob/main/internal/egress/policy.go): `internal/egress/policy.go`

### Other components

- **User**
- [Webhook receiver](https://github.com/work-frame/goflow/blob/main/cmd/receiver/main.go): `cmd/receiver/main.go`
- **PostgreSQL**
- **Redis**

## Connections

- User → CLI: runs
- CLI → API client: calls (evidence: `internal/cli/cli.go`)
- User → Dashboard: uses (evidence: `README.md`)
- Dashboard → Web host: served by (evidence: `README.md`)
- API client → HTTP API: HTTP requests (evidence: `internal/client/client.go`)
- Web host → HTTP API: accesses
- HTTP API → Accounts and sessions: handles auth
- HTTP API → Job model: manages jobs
- HTTP API → Job storage: persists jobs (evidence: `README.md`)
- Job storage → PostgreSQL: reads and writes (evidence: `README.md`)
- HTTP API → Outbox relay: wakes relay (evidence: `README.md`)
- Outbox relay → Redis queue: enqueues IDs (evidence: `README.md`)
- Redis queue → Redis: stores work (evidence: `README.md`)
- Worker pool → Redis queue: takes jobs (evidence: `internal/worker/worker.go`)
- Worker pool → Work and leases: claims and records (evidence: `README.md`)
- Work and leases → PostgreSQL: leases jobs (evidence: `README.md`)
- Worker pool → Job model: routes job types (evidence: `internal/worker/worker.go`)
- Worker pool → Webhook delivery: runs webhook jobs (evidence: `README.md`)
- HTTP API → Live events: publishes changes
- Live events → Event streams: feeds streams
- HTTP API → Metrics: exposes metrics (evidence: `README.md`)
- Webhook delivery → Egress policy: checks destinations (evidence: `README.md`)
- Webhook delivery → Webhook secrets: uses signing secrets (evidence: `internal/database/webhooks.go`)
- Webhook delivery → Webhook receiver: sends signed POST (evidence: `README.md`)
- HTTP API → Webhook secrets: rotates secrets
- HTTP API → Job storage: lists attempts
- Webhook secrets → PostgreSQL: stores encrypted data (evidence: `internal/database/webhooks.go`)
