Runtime Architecture

Understand Alfred's processes, durable state, transient delivery, and provider adapters.

Alfred keeps request handling, durable orchestration, operational projections, and event delivery as separate responsibilities. They share a deployment and schema where practical, but they do not share authority over the same state.

Process Boundaries

Process	Responsibility	Durable dependencies
API	Client, operator, and adapter-ingress route groups in one Hono runtime; auth and RBAC; workflow submission and controls; Workflow SDK serving; SSE	Alfred tables and Postgres World
Dispatcher	claims outbox work, publishes live events, attempts webhook delivery, records outcomes	Alfred outbox and delivery tables
Docs	Fumadocs pages, generated OpenAPI reference, search, OG images, API playground proxy	build-time source and the configured Alfred API origin
Postgres	Alfred application schema plus SDK-owned World schema	Railway-managed storage
Redis	live event fan-out, short-lived stream tokens, and replay protection	transient managed storage

Workflow step functions reuse AWS and vendor adapters from packages/workers. They are libraries called from bounded Workflow SDK steps.

Request Flow

An HTTP workflow request crosses these boundaries in order:

bearer authentication resolves a persisted principal;
RBAC checks the workflow's single workflows:<name> permission;
Zod parses and canonicalizes the request body;
the idempotency key and logical request identity find or create an execution;
a target reservation and concurrency command are persisted when required;
Workflow SDK starts immediately or after the command acquires its lane.

The request returns an execution projection. Provider work continues outside the HTTP connection. See Execution Lifecycle for identity, queueing, continuation, and terminal-state semantics.

Two Postgres Ownership Domains

One Postgres service contains two distinct state models.

Alfred tables store public and operational state:

executions, attempts, workflow run bindings, stages, and waiting reasons;
workflow command ownership and queue order;
principals, API keys, permissions, audit records, and ingress deliveries;
Slack workflow-to-thread bindings and milestone delivery receipts;
outbox events, webhook subscriptions, and delivery attempts.

Workflow SDK Postgres World stores runtime state:

workflow runs and event history;
persisted step inputs and outputs;
durable sleeps and hooks;
SDK-owned worker jobs.

Alfred migrations own the first model. Postgres World's bootstrap and runtime own the second. Sharing a database service does not make either schema safe to edit through the other's migration path.

State Authority

Different questions have different authoritative answers:

Question	Authority
What did the client request?	normalized execution input in Alfred Postgres
Which command owns the AWS lane?	workflow command state in Alfred Postgres
Which durable step completed?	retained Workflow SDK source run
What exactly did a provider mutation change?	validated receipt in persisted step output
What should an operator or client see?	execution and stage projections
Which public events exist?	transactional outbox history
Which events are live right now?	Redis delivery channel

Execution stages may expose receipt summaries for diagnosis. They are not a recovery ledger. Rollback must read the retained source run and fail closed if its versioned receipts are missing or invalid.

Event Delivery

A workflow step records a stable event key and updates the execution projection with the outbox write. The dispatcher then delivers that committed event to Redis and eligible webhook subscribers.

This split gives each channel the right behavior:

polling and replay read durable history from Postgres;
SSE uses Redis for low-latency notification and resumes from durable event sequence numbers;
webhooks are retried as delivery attempts without re-running workflow side effects;
event-key uniqueness prevents a retried emit step from duplicating a logical event.

Redis loss can interrupt a live connection, but it does not erase execution or event history.

Slack Tracking

When Slack is configured, slash commands are verified directly by the Chat SDK adapter. Alfred maps the Slack workspace and user IDs to an RBAC principal, submits the same typed workflow definitions used by the HTTP API, and persists an execution-to-thread binding. Durable workflow progress is read from the Workflow SDK progress stream. The stored stream cursor and milestone ledger let another API instance resume delivery without duplicating stage updates.

Provider Adapter Boundary

Workflow functions contain deterministic orchestration. Side effects run in bounded step functions that may call Postgres, AWS SDK v3, GitHub, ArgoCD, GoDaddy, or Zendesk.

Each mutation step should:

inspect enough current state to calculate a narrow change;
use a stable operation key where the provider supports idempotency;
preserve fields outside that operation's ownership;
return a versioned receipt containing prior and desired state;
classify transient failures as retryable and unsafe business conditions as terminal.

The receipt crosses the forward/recovery boundary. Provider clients remain replaceable as long as they preserve that contract.

Docs Build Boundary

The docs app imports Alfred's shared schemas to generate two OpenAPI documents. Virtual operation pages and the interactive API client use only the client document. Operators can download the separate operator document. Adapter ingress hooks appear in neither contract. Interactive requests use a restricted same-origin proxy that accepts only the configured Alfred API origin. The docs service does not receive AWS or vendor credentials.

On this page