# samudralaajaykumarrr/taskforge architecture

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

## Overview

TaskForge accepts authenticated job and workflow requests, persists durable state in PostgreSQL, and runs jobs through competing workers with leases, heartbeats, retries, cancellation, and timeouts. Workflows add dependency-gated execution on that same job engine. The graph also shows operator controls, retention, and diagnostics. Workflow and several ancillary subsystem links rely on README documentation because their implementation was not sampled; uncertain call wiring is omitted.

Main entry points: [`internal/api`](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/api) (HTTP API), [`internal/worker/worker.go`](https://github.com/samudralaajaykumarrr/taskforge/blob/main/internal/worker/worker.go) (Worker loop), [`internal/store`](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/store) (Job store), [`internal/principal`](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/principal) (Principal and keys)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_submission["Request handling"]
  node_api_process["API process<br/>[main.go]"]
  node_api["HTTP API"]
end

subgraph group_execution["Job execution"]
  node_workflow_engine["Workflow engine"]
  node_worker_process["Worker process<br/>[main.go]"]
  node_worker_loop["Worker loop<br/>[worker.go]"]
  node_handler_registry["Handler registry<br/>[handler.go]"]
  node_job_model["Job model"]
end

subgraph group_persistence["Durable state"]
  node_store["Job store"]
  node_database[("PostgreSQL")]
  node_txenqueue["Transactional enqueue<br/>[txenqueue.go]"]
end

subgraph group_operations["Operations and policy"]
  node_principal_store["Principal and keys"]
  node_governance["Queue governance"]
  node_admin["Admin CLI<br/>[main.go]"]
  node_retention["Retention sweeper"]
  node_retention_process["Retention process<br/>[main.go]"]
end

subgraph group_observability["Diagnostics"]
  node_metrics["Metrics and logs"]
  node_invariants["Invariant checker"]
end

node_caller(("API client"))

node_caller -->|"submits and queries"| node_api
node_api_process -->|"configures and serves"| node_api
node_api -->|"authenticates"| node_principal_store
node_api -->|"reads and writes jobs"| node_store
node_api -->|"handles workflows"| node_workflow_engine
node_api -->|"checks limits"| node_governance
node_api -->|"records metrics"| node_metrics
node_worker_process -->|"runs"| node_worker_loop
node_worker_loop -->|"claims and completes"| node_store
node_worker_loop -->|"dispatches jobs"| node_handler_registry
node_worker_loop -->|"uses job data"| node_job_model
node_workflow_engine -->|"tracks workflow jobs"| node_store
node_store -->|"reads and writes"| node_database
node_principal_store -->|"stores credentials"| node_database
node_governance -->|"stores limits"| node_database
node_admin -->|"manages keys"| node_principal_store
node_admin -->|"configures queues"| node_governance
node_retention_process -->|"runs sweeps"| node_retention
node_retention -->|"deletes expired records"| node_database
node_invariants -->|"checks durable state"| node_database
node_txenqueue -->|"enqueues transactionally"| node_database

click node_api_process "https://github.com/samudralaajaykumarrr/taskforge/blob/main/cmd/api/main.go"
click node_api "https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/api"
click node_workflow_engine "https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/workflow"
click node_worker_process "https://github.com/samudralaajaykumarrr/taskforge/blob/main/cmd/worker/main.go"
click node_worker_loop "https://github.com/samudralaajaykumarrr/taskforge/blob/main/internal/worker/worker.go"
click node_handler_registry "https://github.com/samudralaajaykumarrr/taskforge/blob/main/internal/handler/handler.go"
click node_job_model "https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/job"
click node_store "https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/store"
click node_txenqueue "https://github.com/samudralaajaykumarrr/taskforge/blob/main/txenqueue/txenqueue.go"
click node_principal_store "https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/principal"
click node_governance "https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/governance"
click node_admin "https://github.com/samudralaajaykumarrr/taskforge/blob/main/cmd/taskforge-admin/main.go"
click node_retention "https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/retention"
click node_retention_process "https://github.com/samudralaajaykumarrr/taskforge/blob/main/cmd/taskforge-retention/main.go"
click node_metrics "https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/metrics"
click node_invariants "https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/invariant"

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_api_process,node_api,node_caller toneBlue
class node_workflow_engine,node_worker_process,node_worker_loop,node_handler_registry,node_job_model toneAmber
class node_store,node_database,node_txenqueue toneMint
class node_principal_store,node_governance,node_admin,node_retention,node_retention_process toneRose
class node_metrics,node_invariants toneIndigo
```

## Components

### Request handling

- [API process](https://github.com/samudralaajaykumarrr/taskforge/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [HTTP API](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/api): `internal/api`

### Job execution

- [Workflow engine](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/workflow): `internal/workflow`
- [Worker process](https://github.com/samudralaajaykumarrr/taskforge/blob/main/cmd/worker/main.go): `cmd/worker/main.go`
- [Worker loop](https://github.com/samudralaajaykumarrr/taskforge/blob/main/internal/worker/worker.go): `internal/worker/worker.go`
- [Handler registry](https://github.com/samudralaajaykumarrr/taskforge/blob/main/internal/handler/handler.go): `internal/handler/handler.go`
- [Job model](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/job): `internal/job`

### Durable state

- [Job store](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/store): `internal/store`
- **PostgreSQL**
- [Transactional enqueue](https://github.com/samudralaajaykumarrr/taskforge/blob/main/txenqueue/txenqueue.go): `txenqueue/txenqueue.go`

### Operations and policy

- [Principal and keys](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/principal): `internal/principal`
- [Queue governance](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/governance): `internal/governance`
- [Admin CLI](https://github.com/samudralaajaykumarrr/taskforge/blob/main/cmd/taskforge-admin/main.go): `cmd/taskforge-admin/main.go`
- [Retention sweeper](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/retention): `internal/retention`
- [Retention process](https://github.com/samudralaajaykumarrr/taskforge/blob/main/cmd/taskforge-retention/main.go): `cmd/taskforge-retention/main.go`

### Diagnostics

- [Metrics and logs](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/metrics): `internal/metrics`
- [Invariant checker](https://github.com/samudralaajaykumarrr/taskforge/tree/main/internal/invariant): `internal/invariant`

### Other components

- **API client**

## Connections

- API client → HTTP API: submits and queries
- API process → HTTP API: configures and serves
- HTTP API → Principal and keys: authenticates
- HTTP API → Job store: reads and writes jobs
- HTTP API → Workflow engine: handles workflows
- HTTP API → Queue governance: checks limits
- HTTP API → Metrics and logs: records metrics
- Worker process → Worker loop: runs
- Worker loop → Job store: claims and completes
- Worker loop → Handler registry: dispatches jobs
- Worker loop → Job model: uses job data
- Workflow engine → Job store: tracks workflow jobs
- Job store → PostgreSQL: reads and writes
- Principal and keys → PostgreSQL: stores credentials
- Queue governance → PostgreSQL: stores limits
- Admin CLI → Principal and keys: manages keys
- Admin CLI → Queue governance: configures queues
- Retention process → Retention sweeper: runs sweeps
- Retention sweeper → PostgreSQL: deletes expired records
- Invariant checker → PostgreSQL: checks durable state
- Transactional enqueue → PostgreSQL: enqueues transactionally