Data plane overview

The data plane is seven bounded-context services plus a projector, all under app/. Each service owns its own MySQL schema on HeatWave (ADR 0005). The users, commands and modules services announce every committed change as an event on NATS (ADR 0003), and the projector folds those events into the Valkey settings projection that the hot path reads.

This page is the component view. The rest of the section goes deeper:

• Database design: the conceptual model, the physical schemas, and the integrity rules.
• Caching and write-behind: the read and write paths, with their UML sequence and state diagrams.
• Class design: the UML class diagrams and the design patterns in play.
• Settings projection: the Valkey layout and the rebuild protocol.

Component diagram

flowchart LR
    subgraph services["Data services (app/)"]
        users["users"]
        commands["commands"]
        modules["modules"]
        transactions["transactions"]
        others["loyalty, notifications,<br/>discord-data"]
    end

    subgraph record["State of record"]
        mysql[("MySQL HeatWave<br/>one schema per service")]
    end

    nats(["NATS JetStream"])
    projector["projector"]
    valkey[("Valkey<br/>settings projection")]
    hot["Hot path readers<br/>(ingress workers)"]

    users --> mysql
    commands --> mysql
    modules --> mysql
    transactions --> mysql
    others --> mysql

    users -- "change events" --> nats
    commands -- "change events" --> nats
    modules -- "change events" --> nats

    nats -- "invalidation (broadcast)" --> services
    nats -- "durable group" --> projector
    projector --> valkey
    hot --> valkey

Ownership

Cross-service references are a plain indexed Twitch user ID column. There are no foreign keys across schemas, by construction.

Event contracts

The subjects and payload DTOs live in internal/domain/event/data and are a public contract: renaming a subject or narrowing a payload is a breaking change. The change events carry the full new state (event-carried state transfer), so consumers never read another service’s schema and redelivery is harmless.

All data.> subjects are captured by the BAGEL_DATA JetStream stream (5 minute retention, file storage, three replicas, pkg/bus/streams.go).

Two subscription shapes, on purpose:

• Broadcast (no queue group): cache invalidation. Every instance of a service drops its cached keys when any instance writes.
• Durable queue group: the projector, and the reproject responders. Exactly one consumer per group handles each event, and the group keeps its position across restarts.

Consumers validate every payload and drop (log and ack) what fails to decode or validate. Nacking a poison message would redeliver it forever.

Configuration

Every service reads its configuration from the environment. Common variables:

Monitoring is a no-op without a license key, so local development needs none of the NEW_RELIC_* variables.