Caching & Schema
In-Memory Cache
The orchestrator uses a Moka-based LRU cache (HighPerfCache) to reduce database roundtrips for hot workflow state. This is an in-process cache — no external dependency required.
Cache Tiers
| Cache | Max Entries | TTL | Purpose |
|---|---|---|---|
| Workflow state | 10,000 | 5 min | Active workflow execution data |
| Journal entries | 5,000 | 1 min | Recent journal entries for replay |
| Claims | 50,000 | 2 min | Workflow claim ownership (shorter than claim timeout) |
How It Works
The HighPerfCache sits between the dispatch engine and PostgreSQL:
- On poll — Check cache for workflow state before querying the database
- On update — Invalidate cached entry so the next read fetches fresh data
- On eviction — LRU eviction when cache is full; no data loss since PostgreSQL is authoritative
Cache metrics (hits, misses, invalidations) are tracked for monitoring.
Memory Impact
| Concurrent Workflows | Approximate Cache Memory |
|---|---|
| Up to 100 | ~50 MB |
| 100–1,000 | ~200 MB |
| 1,000–5,000 | ~500 MB |
| 5,000–10,000 | ~1 GB |
Memory usage scales with the number of active (not total) workflows.
Database Schema Details
Workflow Claiming
The workflow_executions table uses claim-based polling for safe distributed work assignment:
1-- Workers claim workflows with SELECT FOR UPDATE SKIP LOCKED2-- This avoids contention between multiple orchestrator nodes3SELECT * FROM workflow_executions4WHERE task_queue = $15 AND namespace = $26 AND status IN ('pending', 'running')7 AND claimed_at IS NULL8ORDER BY priority DESC, submitted_at ASC9FOR UPDATE SKIP LOCKED10LIMIT 1;Key columns: claimed_by, claim_timeout_at, pending_requeue, shard_id, priority.
Journal (Event Sourcing)
Every workflow step is recorded in the journal for replay protection:
1-- Journal entries for a workflow execution2SELECT * FROM workflow_execution_journal3WHERE execution_id = $14ORDER BY sequence_number ASC;Entry types include: WorkflowStarted, StepCompleted, TimerStarted, TimerFired, EventReceived, WorkflowCompleted, WorkflowFailed.
Outbox Pattern
Task dispatch uses the outbox pattern for atomic delivery:
1-- State change + outbox insert in one transaction2BEGIN;3 UPDATE workflow_executions SET status = 'running' WHERE id = $1;4 INSERT INTO outbox_queue (execution_id, task_queue, namespace, payload)5 VALUES ($1, $2, $3, $4);6COMMIT;78-- OutboxProcessor claims entries with lease-based locking9UPDATE outbox_queue10SET status = 'processing', lease_expires_at = NOW() + INTERVAL '30 seconds'11WHERE status = 'pending'12LIMIT 1013RETURNING *;Next Steps
- Storage Overview — PostgreSQL configuration and migrations
- Redis — Optional Redis configuration for fast queue notification
- Operations & Troubleshooting — Docker Compose setup and troubleshooting