# karthik-valmiki/asyncz architecture

> Architecture diagram of the GitHub repository karthik-valmiki/asyncz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karthik-valmiki/asyncz
- Repository: https://github.com/karthik-valmiki/asyncz

## Overview

AsyncZ accepts jobs over HTTP, persists them before enqueueing, and returns an ID for polling. Workers execute jobs asynchronously, record attempts, retry failures, and send exhausted or zombie jobs to a dead-letter queue. The README documents these recovery capabilities; worker excerpts are partial, so internal steps not shown there are represented only where documented.

Main entry points: [`app/main.py`](https://github.com/karthik-valmiki/asyncz/blob/main/app/main.py) (FastAPI), [`app/worker.py`](https://github.com/karthik-valmiki/asyncz/blob/main/app/worker.py) (Worker), [`app/db.py`](https://github.com/karthik-valmiki/asyncz/blob/main/app/db.py) (DB Sessions), [`app/redis_client.py`](https://github.com/karthik-valmiki/asyncz/blob/main/app/redis_client.py) (ARQ Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["HTTP API"]
  node_api["FastAPI<br/>[main.py]"]
  node_schemas["API Schemas<br/>[schemas.py]"]
  node_result["Job Status<br/>[main.py]"]
end

subgraph group_durability["Durable State"]
  node_dbaccess["DB Sessions<br/>[db.py]"]
  node_models["Job Models<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
  node_attemptlog[("Attempt Audit<br/>[models.py]")]
end

subgraph group_processing["Job Processing"]
  node_redisclient["ARQ Client<br/>[redis_client.py]"]
  node_queue["ARQ Queue<br/>[redis_client.py]"]
  node_redis[("Redis")]
  node_worker["Worker<br/>[worker.py]"]
  node_execution["Payload Execution<br/>[worker.py]"]
  node_recovery["Zombie Recovery<br/>[worker.py]"]
end

subgraph group_operations["Monitoring"]
  node_dlq["Dead Letter Queue<br/>[main.py]"]
  node_health["Health Checks<br/>[main.py]"]
end

node_client(("Client"))

node_client -->|"submits or polls"| node_api
node_api -->|"validates and formats"| node_schemas
node_api -->|"reads and writes"| node_dbaccess
node_api -->|"queries jobs"| node_models
node_dbaccess -->|"persists state"| node_postgres
node_api -->|"enqueues job"| node_redisclient
node_redisclient -->|"pushes job"| node_queue
node_queue -->|"stores queued work"| node_redis
node_redis -->|"dispatches jobs"| node_worker
node_worker -->|"loads and updates"| node_dbaccess
node_worker -->|"uses job records"| node_models
node_worker -->|"records attempts"| node_attemptlog
node_worker -->|"runs payload"| node_execution
node_execution -->|"returns outcome"| node_worker
node_worker -->|"retries or dead-letters"| node_redis
node_worker -->|"runs scheduled scan"| node_recovery
node_recovery -->|"finds stale jobs"| node_dbaccess
node_recovery -->|"re-enqueues or dead-letters"| node_redis
node_api -->|"reads DLQ and health"| node_redis
node_api -->|"returns job state"| node_result
node_api -->|"checks dependencies"| node_health
node_api -->|"returns response"| node_client

click node_api "https://github.com/karthik-valmiki/asyncz/blob/main/app/main.py"
click node_schemas "https://github.com/karthik-valmiki/asyncz/blob/main/app/schemas.py"
click node_dbaccess "https://github.com/karthik-valmiki/asyncz/blob/main/app/db.py"
click node_models "https://github.com/karthik-valmiki/asyncz/blob/main/app/models.py"
click node_redisclient "https://github.com/karthik-valmiki/asyncz/blob/main/app/redis_client.py"
click node_queue "https://github.com/karthik-valmiki/asyncz/blob/main/app/redis_client.py"
click node_worker "https://github.com/karthik-valmiki/asyncz/blob/main/app/worker.py"
click node_execution "https://github.com/karthik-valmiki/asyncz/blob/main/app/worker.py"
click node_attemptlog "https://github.com/karthik-valmiki/asyncz/blob/main/app/models.py"
click node_recovery "https://github.com/karthik-valmiki/asyncz/blob/main/app/worker.py"
click node_dlq "https://github.com/karthik-valmiki/asyncz/blob/main/app/main.py"
click node_result "https://github.com/karthik-valmiki/asyncz/blob/main/app/main.py"
click node_health "https://github.com/karthik-valmiki/asyncz/blob/main/app/main.py"

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,node_schemas,node_result,node_client toneBlue
class node_dbaccess,node_models,node_postgres,node_attemptlog toneAmber
class node_redisclient,node_queue,node_redis,node_worker,node_execution,node_recovery toneMint
class node_dlq,node_health toneRose
```

## Components

### HTTP API

- [FastAPI](https://github.com/karthik-valmiki/asyncz/blob/main/app/main.py): `app/main.py`
- [API Schemas](https://github.com/karthik-valmiki/asyncz/blob/main/app/schemas.py): `app/schemas.py`
- [Job Status](https://github.com/karthik-valmiki/asyncz/blob/main/app/main.py): `app/main.py`

### Durable State

- [DB Sessions](https://github.com/karthik-valmiki/asyncz/blob/main/app/db.py): `app/db.py`
- [Job Models](https://github.com/karthik-valmiki/asyncz/blob/main/app/models.py): `app/models.py`
- **PostgreSQL**
- [Attempt Audit](https://github.com/karthik-valmiki/asyncz/blob/main/app/models.py): `app/models.py`

### Job Processing

- [ARQ Client](https://github.com/karthik-valmiki/asyncz/blob/main/app/redis_client.py): `app/redis_client.py`
- [ARQ Queue](https://github.com/karthik-valmiki/asyncz/blob/main/app/redis_client.py): `app/redis_client.py`
- **Redis**
- [Worker](https://github.com/karthik-valmiki/asyncz/blob/main/app/worker.py): `app/worker.py`
- [Payload Execution](https://github.com/karthik-valmiki/asyncz/blob/main/app/worker.py): `app/worker.py`
- [Zombie Recovery](https://github.com/karthik-valmiki/asyncz/blob/main/app/worker.py): `app/worker.py`

### Monitoring

- [Dead Letter Queue](https://github.com/karthik-valmiki/asyncz/blob/main/app/main.py): `app/main.py`
- [Health Checks](https://github.com/karthik-valmiki/asyncz/blob/main/app/main.py): `app/main.py`

### Other components

- **Client**

## Connections

- Client → FastAPI: submits or polls
- FastAPI → API Schemas: validates and formats
- FastAPI → DB Sessions: reads and writes
- FastAPI → Job Models: queries jobs
- DB Sessions → PostgreSQL: persists state
- FastAPI → ARQ Client: enqueues job
- ARQ Client → ARQ Queue: pushes job
- ARQ Queue → Redis: stores queued work
- Redis → Worker: dispatches jobs
- Worker → DB Sessions: loads and updates
- Worker → Job Models: uses job records
- Worker → Attempt Audit: records attempts
- Worker → Payload Execution: runs payload
- Payload Execution → Worker: returns outcome
- Worker → Redis: retries or dead-letters
- Worker → Zombie Recovery: runs scheduled scan
- Zombie Recovery → DB Sessions: finds stale jobs
- Zombie Recovery → Redis: re-enqueues or dead-letters
- FastAPI → Redis: reads DLQ and health
- FastAPI → Job Status: returns job state
- FastAPI → Health Checks: checks dependencies
- FastAPI → Client: returns response