Relay architecture: bounded capabilities, not a prescribed stack

The architecture is designed to keep stable mechanics separate from the product’s changing decisions. It deliberately provides no mechanism for automatic urgency classification in the first foundation slice. That possible feature remains a product experiment.

Dependency structure

Open full-size diagram

The diagram describes one sensible implementation, not a universal requirement for three layers or plugins. A monolith may use the same boundaries internally. A set of services may expose them through remote APIs. A game may use engine plugins and data assets.

Layers and invariants

Mechanics (stable capabilities)

• RequestStore: create and retrieve durable request records; enforce key-based idempotency and version semantics.
• AuditSink: record significant state transitions without depending on user-interface code.
• NotificationPort: accept notification intents without exposing provider-specific implementation to product workflows.

Their responsibilities should not depend on whether Relay eventually needs automatic urgency, smart scheduling or more dashboards.

Integration (composition)

• RequestIntake: validates a submission, calls the store and emits a creation event only for a new request.
• AssignmentWorkflow: applies authorised state changes through the store, logs the transition and requests a notification.

It must not replicate persistence rules in a separate local cache or construct a second request identity model.

Product orchestration (evolving behaviour)

• QueuePolicy: selects which requests are shown and how missing ownership is highlighted.
• UserWorkflow: chooses which product actions are exposed and which user questions require more evidence.

Product experiments belong here when possible. If an experiment demands a mechanics-level change, that is an explicit architectural decision.

Complementary tool pipeline

A fixture generator, schema validator, dependency check and test runner help every layer. They are development capabilities, not another runtime product tier.

Contract-first implementation context

An agent implementing a queue view should receive the request read contract, relevant product behaviour and tests. It does not need the storage adapter internals.

An agent changing storage should receive the behavioural store contract, current adapter and consumer tests. It does not need the complete product-market analysis, except where design decisions depend on it.

Where work crosses boundaries, expand context deliberately and record the contract impact. Small context is a consequence of good boundaries, not a reason to hide required information.

Architectural constraints

• Product workflow components cannot import storage-provider implementations directly.
• Integration components use RequestStore, AuditSink and NotificationPort abstractions.
• A replay must not create a new request or duplicate a creation audit event.
• Contradictory duplicate payloads are errors, not silent overwrites.
• Changing contracts requires an explicit decision and corresponding consumer tests.
• Identity, tenant separation, concurrency and durability require production implementations; the executable reference is intentionally in-memory.

Questions the architecture doesn’t answer

Authentication design, tenant tenancy model, database selection, event delivery guarantees, retry/backoff policy, disaster recovery, observability and jurisdiction-specific data handling. Those need proportionate design before production release. Their absence from the teaching example should not be mistaken for production sufficiency.

See behavioural contracts, ADR and delivery phases.