Relay — Software Requirements Specification

Version: 1.17 (draft) Status: For review Companion documents: 01-product-vision.md, 02-personas.md, 03-journey-map.md Structure: adapted from ISO/IEC/IEEE 29148

Table of contents

1. Introduction
2. Overall description
3. External interface requirements
4. Functional requirements
5. Non-functional requirements
6. Data requirements
7. Traceability
8. Appendices

1. Introduction

1.1 Purpose

This document specifies the functional and non-functional requirements for Relay, a multi-tenant chat infrastructure platform delivered as an API. It is the reference for implementation, test design, and acceptance.

It defines what the system must do. Component decomposition, technology selection beyond stated constraints, and deployment topology belong to the architecture and design documents.

1.2 Scope

Relay provides real-time messaging as a service to software companies who embed it in their own applications. It supplies message transport, persistence, membership, delivery guarantees, webhooks, and usage analytics. It does not supply a user-facing chat application.

In scope

Multi-tenant organisation and application management · API key lifecycle · delegated end-user authentication · channels and membership · message send, edit, delete, and history · real-time delivery over WebSocket · presence and typing indicators · Unicode emoji and customer-defined emoji packs that end users browse and install · hosted media attachments (image, audio, video) with direct-to-storage upload, scanning, and signed delivery · webhook dispatch with retry · per-tenant rate limiting and quotas · usage metering · a developer dashboard · a JavaScript client SDK.

Out of scope for v1

End-to-end encryption · voice and video calls · native iOS and Android SDKs · a hosted end-user chat application · identity provision (customers own their user directory) · message search · threads and reactions · media transcoding beyond thumbnail/poster generation · on-premise deployment.

1.3 Definitions

1.4 Requirement conventions

Priority — aligned to the phased roadmap in the vision document:

Verification method — T test (automated) · D demonstration · I inspection · A analysis (including load testing).

Requirements use shall for obligations. Each has a unique, stable identifier; identifiers are never reused after removal.

2. Overall description

2.1 Product perspective

Relay is a new, self-contained system with no predecessor. It sits between a customer's application backend and their end-user clients.

flowchart TB
    clients["Customer's end-user clients (web / mobile)"]
    backend["Customer's application backend"]

    subgraph relay [RELAY]
        rest["REST API"]
        gw["WebSocket gateway"]
        whd["Webhook dispatcher"]
        pg[("PostgreSQL<br/>(OLTP)")]
        q[["Queue"]]
        ch[("ClickHouse<br/>(OLAP)")]
        rest --> pg
        gw --> pg
        q --> whd
        q --> ch
    end

    clients -- "user token (JWT)<br/>WebSocket + REST" --> relay
    relay -- "real-time events" --> clients
    backend -- "API key (REST)" --> relay
    relay -- "signed webhooks" --> backend

The customer's backend is the trust anchor: it authenticates its own users and mints user tokens. Relay verifies those tokens but never holds end-user credentials.

2.2 User classes

2.3 Operating environment

Server: Linux, containerised, horizontally scalable. PostgreSQL 15+ for operational data; ClickHouse 24+ for analytical data; Redis or NATS for pub/sub fan-out and presence; a durable queue (Kafka, Redpanda, or NATS JetStream) between the operational and analytical paths.

Client: the SDK shall support evergreen Chrome, Firefox, Safari, and Edge; Node.js 18+; and React Native 0.72+.

2.4 Constraints

2.5 Assumptions and dependencies

3. External interface requirements

3.1 REST API

Error response format

{
  "code": "channel_member_limit_exceeded",
  "message": "Channel has reached its maximum of 1000 members.",
  "field": "user_ids",
  "docs_url": "https://docs.relay.dev/errors/channel_member_limit_exceeded",
  "request_id": "req_01HQ8X..."
}

Amended in 1.3. This example nested the five fields under an error key until 2026-08-20. The implementation has emitted them top-level since the walking skeleton, and the document is being brought to the code rather than the reverse — recorded because the constitution's Governance section requires a conflict with this document to be resolved by explicit amendment rather than ignored.

The flat shape is also the one that keeps EIR-API-04's stated purpose intact. The same five fields travel on the WebSocket surface inside a frame's payload (EIR-WS-02), so a REST body nested under error would make the two surfaces differ in two ways instead of one: the transport wrapper, which is unavoidable, and the field container, which is not.

3.2 WebSocket interface

3.3 Webhook interface

3.4 Dashboard interface

4. Functional requirements

4.1 Tenancy and application management — FR-TEN

FR-TEN-05 is the single most important requirement in this document. A violation is classified Sev-0. Verification includes an automated cross-tenant access test suite executed against every endpoint on every build.

4.2 Authentication and authorisation — FR-AUT

Design note (journey Stage 4). Confusion between API keys and user tokens is the most common first-integration failure. FR-AUT-03 and FR-AUT-09 exist specifically to reduce it, and the error message for using the wrong credential type must name the mistake explicitly.

4.3 User management — FR-USR

AMENDMENT, chapter 3.17 — FR-USR-07 and FR-MSG-15 added, FR-MSG-13 and FR-RTL-05 narrowed. Until this chapter a message sent with an application key named nobody, and the SRS had no word for the thing a customer's software is. Three chapters since have made the sender decide what is rendered, what is delivered and what may be seen, so a message with no sender became a row those three chapters cannot describe.

FR-USR-07 is new: a bot user, carrying a description, that cannot authenticate. It is not a new kind of row — it is a users row with a stored property — because every reader built since chapter 3.15 already reads that table.

FR-MSG-13 was already here, and it is being MET rather than introduced. It has said since v1 that a key may send on behalf of a user, and chapter 3.3 satisfied it by sending unattributed — a decision that was right when nothing read the sender, and that messages.controller.ts has recorded ever since as "A tenant's own server sending on a customer's behalf is FR-MSG-13, not a mistake." This chapter is the first implementation that names the user. The clause is narrowed from any user to a bot user of that tenant, in place: adding a clause beside it would have left this document asserting both that a key may send as anyone and that it may send only as a bot.

FR-MSG-15 carries only what FR-MSG-13 does not — that every message has a sender at all.

FR-RTL-05 is narrowed from "unique active users" to "unique active persons", and FR-ANL-05 is deliberately unchanged. A bot is metered like any user and is exempt from the enforced ceiling: the ceiling bounds a customer's human population, and a customer's own software should not be able to lock their people out of sending. Metering and enforcement were already two clauses in two families before this chapter needed them to be.

FR-RTL-08's exception, stated rather than discovered. "Quota exhaustion shall degrade predictably: sends rejected with a specific error code." A bot's send is not rejected at exhaustion. Uncited that is a defect report; here it is a decision.

FR-MSG-01 is unchanged — it describes what a message contains and does not mention a sender. A later reader must not look for the sender rule there. FR-MSG-08 is unchanged too, and worth naming: its tombstone already retains the author, which agrees with FR-MSG-15 and has never been built.

How the two new clauses are verified (T073). FR-USR-07 by test: the bot round trip, the description rules at the boundary and at the database, and the promotion in all three of its states. FR-MSG-15 by compilation as well as by test — repository.sendMessage takes userId: string, so a senderless write does not build, and the evidence is a typecheck transcript rather than a failing test. A compile-time guarantee has no red test to watch, which is why the amendment says so here rather than leaving a reader to look for one.

FR-USR-01 still holds for bots. "Relay shall not generate end-user identities" — a bot's identifier is customer-supplied like any other, and the platform invents nothing. The alternative this chapter rejected was a synthetic sender the platform mints for a key, which is what chapter 3.10 argued against and still argues against; a bot is a declared identity the customer creates, names and describes.

Verification, FR-USR-02 to FR-USR-06 (chapters 3.15 and 3.16). Five of these six clauses were unimplemented until then, and two things are worth recording beyond "tested".

FR-USR-02 had a symptom rather than a gap: minting a token for an unknown identifier and sending through the internal route answered 400 "unknown user", which names the caller when the cause is that nobody created a row. Implicit creation now happens on the mint path, and the response deliberately does not distinguish "created" from "existed" — a status that did would let a caller enumerate a tenant's external ids.

FR-USR-03's two bounds are 4 KB for a user against FR-CHN-01's 8 KB for a channel. The difference is row cardinality and is now stated where the constant is: users outnumber channels 3.4:1 on the test lane and the ratio only grows, because a channel is created deliberately and a user row appears for every end user who authenticates.

FR-USR-05 keeps the row. ON DELETE SET NULL on messages.user_id satisfies the letter of "preserving their messages" and breaks delivery: the resume path drops a senderless row, so every message a deleted user ever sent would vanish from every reconnecting client with a sequence gap as the only trace. Verified on the socket, not only in storage.

FR-USR-06 is enforced at connect and on the send path, and the ban check runs before the channel is resolved — so a banned user gets one answer for every channel id and cannot enumerate them. An already-open socket stops writing and keeps receiving, which is the shape FR-AUT-11 already required for an expired token.

4.4 Channels and membership — FR-CHN

Verification, FR-CHN-03 to FR-CHN-10 (chapters 3.15 and 3.16). channels.type had carried public | private with a CHECK constraint since the first migration while no decision consulted it — it was declared, selected and returned by the create route, so "nothing reads it" was false and "nothing decides on it" was the true and sharper statement. FR-CHN-03 and FR-CHN-05 are what made it decide.

FR-CHN-05 has four doors — the send path, the read-by-id path, the history path and the socket session — and the enum accepting private was widened last, after all four held. Each refusal is byte-identical to a channel that does not exist, verified by the same indistinguishability oracle NFR-SEC-09's suite uses for cross-tenant attacks, extended with a same-tenant fixture. A 403 naming the membership would announce that the channel exists.

FR-CHN-04's roles are not FR-TEN-07's. owner, moderator, member against an organisation's owner, admin, member — one word apart, and a migration reusing the organisation's constraint would accept admin on a channel member and look correct in review. Both CHECK constraints now name the other. The listing returns a member's role and no operation is authorized by it, which is the statement worth making rather than "nothing reads it".

FR-CHN-09's count has no counter: greatest(last_sequence − read_position, 0), because last_sequence is already the sequencing authority. Measured against 1,000,000 messages, counting rows past the position is 9.8–13.4 ms, a cached counter is 1.2–2.1 ms and the subtraction is 1.1–4.5 ms — the counter is no faster and adds a value that can go stale. The approximation this accepts is stated: a deleted message still counts as one unread, because a tombstone keeps its sequence.

FR-CHN-08's ordering key is indexed and the index is earned. Ordering by the last message's timestamp costs 0.87 ms on the test lane and 159 ms at 1,000,000 messages with a sequential scan over every message in the environment; an indexed channels.last_activity_at is 1.1 ms. The listing's own plan was measured at four scales, and the first page is the most expensive one — the reverse of an offset paginator, because a keyset narrows the input set as it pages.

FR-CHN-10's refusal order is part of the requirement. Ban, then membership and visibility, then archive. Reverse the last two and a non-member of a private archived channel learns it exists from channel_archived.

4.5 Messaging — FR-MSG

Message state machine (client-observable)

stateDiagram-v2
    composing --> sending: send()
    sending --> sent: ack
    sending --> failed: timeout / 5xx
    failed --> sending: retry with same idempotency key
    sent --> edited: edit
    sent --> deleted: delete

The SDK shall surface sending, sent, and failed distinctly (see FR-SDK-05) so that customer interfaces can represent delivery honestly rather than optimistically.

4.6 Real-time delivery — FR-RTM

4.7 Webhooks — FR-WHK

4.8 Rate limiting and quotas — FR-RTL

Design note. FR-RTL-06 is a purchasing requirement, not a technical one. Unbounded cost exposure is David's principal objection (journey, diligence phase).

4.9 Analytics and metering — FR-ANL

FR-ANL-11 matters. The analytical store is optimised for aggregate queries, retained longer, and accessed by more internal systems. Message content stays in the operational store, where deletion semantics are enforceable.

4.10 Moderation and compliance — FR-MOD

4.11 Developer dashboard — FR-DSH

FR-DSH-02 is the highest-leverage single feature in the product (journey, Stage 4). Seeing the first message arrive in the dashboard converts uncertainty into confidence faster than documentation can.

4.12 Client SDK — FR-SDK

4.13 Emoji and emoji packs — FR-EMJ

Two distinct capabilities: Unicode emoji (standard emoji inside message text — a correctness obligation, Phase 1) and custom emoji packs (customer-defined emoji that end users browse and install — a feature, Phase 3+).

Unicode emoji

Custom emoji packs

Design notes. (1) Relay hosts no emoji images in v1 — packs reference customer-hosted URLs, consistent with FR-MSG-11 and the file-storage exclusion. Image availability and CDN caching are the customer's responsibility and shall be documented. (2) FR-EMJ-09 is a deliberate stance: making installation a permission would put an authorisation check on the message hot path and create a support-facing failure mode ("my emoji stopped working") for no security benefit — shortcodes are environment-public by construction. (3) FR-EMJ-10 exists for Priya: a dispute record must render as it was written, even if the pack was deleted since (journey 3, stage 3).

4.14 Hosted media — FR-MED

Relay hosts media attachments: image, audio, and video. The design principle, defended in SAD ADR-13: bytes never transit Relay's compute — clients upload directly to object storage via presigned URLs and download via signed URLs; Relay's services handle only metadata, authorisation, and the scan pipeline.

Upload

Attachment and delivery

Lifecycle, quota, and compliance

Design notes. (1) FR-MED-06 permits attaching pending media so a photo can be sent the moment upload completes, with recipients seeing a placeholder until the scan clears — matching user expectations set by consumer messengers. The scan is a delivery gate for bytes, never for the message. (2) FR-MED-08 makes authorisation follow the message, not the file: media access control inherits channel visibility rather than inventing a parallel ACL system. Inherits is load-bearing and was measured against the platform at chapter 4.12: reading the clause's earlier wording literally, as a membership check, would have refused a user the photo in a message whose text they can read — 11,557 public channels against 1,016 private on the development lane, so the common case is a channel where membership is not the rule. The clause is satisfied by construction only if no second predicate is written, which is why the delivery route calls the same channelVisibleTo every read route calls. The same reasoning settles the unreferenced object: granting its uploader access would be a second authorisation rule that does not follow a message, and FR-MED-10 hard-deletes such objects after 24 hours, so it would be a read path to a thing already scheduled for destruction. (3) This section reverses Appendix B's original exclusion; the reversal rationale is recorded there.

5. Non-functional requirements

5.1 Performance — NFR-PRF

5.2 Scalability — NFR-SCL

5.3 Reliability and availability — NFR-REL

5.4 Security — NFR-SEC

5.5 Observability — NFR-OBS

5.6 Maintainability and portability — NFR-MNT

5.7 Developer experience — NFR-USE

These are product requirements expressed as measurable outcomes; they are the acceptance criteria for journey Stages 2–4.

6. Data requirements

6.1 Operational entities (PostgreSQL)

erDiagram
    Organisation ||--o{ Application : "1:N"
    Application ||--|{ Environment : "1:2 (dev/prod)"
    Environment ||--o{ ApiKey : "1:N"
    Environment ||--o{ User : "1:N"
    Environment ||--o{ MediaObject : "1:N"
    Environment ||--o{ Channel : "1:N"
    Environment ||--o{ EmojiPack : "1:N"
    Environment ||--o{ WebhookEndpoint : "1:N"
    Environment ||--o{ AuditLogEntry : "1:N"
    User }o--o{ EmojiPack : "installs (N:M)"
    MediaObject ||--o{ DerivedObject : "1:N"
    Channel ||--o{ Member : "1:N"
    Member }o--|| User : "N:1"
    Channel ||--o{ Message : "1:N"
    Message ||--o{ MessageEdit : "1:N"
    EmojiPack ||--o{ Emoji : "1:N"
    WebhookEndpoint ||--o{ WebhookDelivery : "1:N"

Key attributes

Integrity requirements

6.2 Analytical events (ClickHouse)

7. Traceability

7.1 Requirements by persona

7.2 Requirements by journey stage

7.3 Phase summary

8. Appendices

Appendix A — Requirement count

Phase 1 delivers 57 requirements. That is the realistic first milestone; everything beyond it is sequenced, not simultaneous. Note that only two emoji requirements (Unicode correctness) sit in Phase 1 — the pack system is deliberately deferred to Phase 3, where its browse/install surface and usage analytics arrive together. Hosted media (§4.14) also lands in Phase 3: it depends on tenancy and quotas (Phase 2) and shares Phase 3's queue and metering machinery, and it has visibly grown that phase — Phase 3 is now the second largest and should be watched for schedule risk.

Appendix B — Deliberately excluded, with reasons

Appendix C — Open questions

Appendix D — Revision history