← Experience
WARDRIGHT REFERENCE SYSTEM
Relay
Workflow Orchestration & Integration Reference System
A database-backed reference system for synthetic event intake, normalization, rule-based routing, approval gates, simulated deliveries, failure handling, and inspectable history.
Technical stack at a glance
- Frontend
- Next.js 15 · React 19 · TypeScript
- Backend
- Node.js worker · Zod · Server APIs
- Database
- PostgreSQL · Transactions · SQL
- Processing
- SKIP LOCKED · Retry · Dead letters
- Infrastructure
- Railway · Cloudflare Worker
- Verification
- Vitest · Playwright · Chromium · SHA-256
Engineering behind Relay
System architecture
- Separate web and worker processes — Next.js handles UI and API; a separate Node.js worker continues processing independently of the browser.
- PostgreSQL as source of truth — Events, states, approvals, queues, attempts, exceptions, and audits persist in the database.
- Database-backed work queues — Transactional row locks and SKIP LOCKED support concurrent workers without Redis, Kafka, or RabbitMQ.
- Explicit workflow transitions — Intake, validation, normalization, routing, approval, delivery, retry, and terminal disposition generate processing evidence.
- Concurrency-safe decisions — Approval and requeue lock workflows; constraints and transactions prevent duplicates and competing decisions.
- Bounded failure handling — Three attempts; synthetic one- and two-second retries; dead-letter handling and generation-preserving requeue.
- Visitor isolation and lifecycle — Signed isolated 24-hour anonymous workspaces, atomic canonical reset, and revision-preserved audit history.
- Layered protection — Cloudflare Worker IP controls and forwarded origin secret; middleware rejects untrusted production requests except shallow process health.
Application development
- Next.js 15, React 19, TypeScript, Zod, custom CSS, Vitest, Playwright/Chromium — Framework, console, validation, design system, and verification.
- Workflow-specific console — Overview, Event Inbox, Approvals, Deliveries, Dead Letter, and Audit queues.
- Reusable presentation components — Metrics, headings, icons, identity, statuses, and shared Wardright CSS tokens.
- Operational navigation — Metrics link to appropriate filtered queues.
- Asynchronous interface behavior — Periodic refresh, pending/error handling, and stale detail-response protection.
- Accessible controls — Keyboard-operable controls, visible focus, dialog containment, Escape, and focus restoration.
- Responsive information density — Reflowing metrics and panels; contained table scrolling without page overflow.
- Deliberate interaction affordances — Non-selectable chrome with selectable event, audit, and payload content.
- Continuous provenance — Wardright Reference System · Synthetic demonstration data · Not customer or federal past performance.
Data & integration
- Relational domain model — Workspaces, sources, routing rules, inbound/normalized events, workflows, steps, approvals, deliveries, attempts, dead letters, audits, and limits.
- Strict ingestion contract — Origin checks, size limits, schema validation, raw validated payload, and canonical normalized form.
- Idempotent intake — Workspace source/event identity and SHA-256 digest distinguish exact replay from conflicting replay.
- Deterministic routing — Priority rules; seeded severity 4–5 requires approval, severity 1–3 proceeds toward delivery.
- Transactional consistency — State transitions, steps, attempts, and audit records commit together.
- Inspectable delivery evidence — Generation, attempt, outcome, reason, and timing; requeue preserves prior failures.
- Database-enforced audit protection — Triggers block UPDATE, DELETE, and TRUNCATE on audit events and partitions.
- Explicit retention boundary — Audit partitions by workspace expiry day; retention removes expired partitions, not indefinite archival.
- Versioned migrations and bound SQL — Advisory-locked migrations and parameterized pg queries.
Deployment & operations
- Railway configuration — Separate web and worker services with private PostgreSQL; web runs migrations before startup.
- Runtime configuration — DATABASE_URL, WORKSPACE_SIGNING_KEY, RELAY_EDGE_SECRET, optional WORKER_POLL_MS; Cloudflare RELAY_ORIGIN and EDGE_ORIGIN_KEY.
- Two health levels — /api/live process check; protected /api/health database and migration readiness.
- Two rate-control layers — PostgreSQL workspace limits; Cloudflare 120 reads and 20 mutations/minute IP limits, eventually consistent per location.
- Durable recovery — Database-backed pending work survives restarts; eligible dead letters can be requeued.
- Operational monitoring — Worker errors, queue age, retries, dead letters, health, capacity, connections, and cleanup require observation.
- Database stewardship — Backup, restore, migration, managed-PostgreSQL, and retention responsibilities; repository does not establish managed backup service.
- Release verification — Saved candidate passed typecheck, production build, 15 model/edge/integration tests, and 9 browser tests covering workflows, isolation, audit, and keyboard/mobile behavior.