# jobqueue docs

Detailed architecture and runtime docs for `jobqueue`.

## Doc map

| File | Purpose |
| --- | --- |
| [`architecture.md`](./architecture.md) | Static architecture, module boundaries, data model, event model, state model |
| [`runtime-lifecycle.md`](./runtime-lifecycle.md) | Step-by-step runtime behavior from startup through shutdown |
| [`integration-findings.md`](./integration-findings.md) | Multi-agent scan results, verified bugs, fixes, and remaining behavioral notes |
| [`jobqueue.c4`](./jobqueue.c4) | LikeC4 source for landscape, container, component, and runtime views |

## Mental model

`jobqueue` is a **single-process orchestrator** around a SQLite-backed job table.

1. Consumer code creates a `JobQueue`.
2. Jobs are persisted immediately in SQLite.
3. A pump claims runnable jobs and hands them to a concurrency-limited worker pool.
4. `PhaseRunner` executes configured phases and reports progress back through `JobQueue`.
5. `JobQueue` persists each state transition, emits typed events, formats SSE payloads, and optionally sends webhooks.
6. A retention scheduler can mark old jobs as `stale` and later delete them.

## Rendering LikeC4 views

The repository stores LikeC4 source in [`jobqueue.c4`](./jobqueue.c4).

```bash
npx likec4 start docs/jobqueue.c4
```

Recommended views in the file:

- `index` - system landscape
- `library` - container view of `jobqueue`
- `runtime` - internal runtime/component view
- `enqueue-to-complete` - dynamic happy path
- `retry-flow` - dynamic retry path