Relay — Software Requirements Specification

Version: 1.0 (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

{
  "error": {
    "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..."
  }
}

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

4.4 Channels and membership — FR-CHN

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 membership rather than inventing a parallel ACL system. (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