# cbschuld/valkey-pubsub architecture

> Architecture diagram of the GitHub repository cbschuld/valkey-pubsub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cbschuld/valkey-pubsub
- Repository: https://github.com/cbschuld/valkey-pubsub

## Overview

##### Project Type and Purpose
- **Type**: A lightweight, TypeScript-native Pub/Sub library.
- **Purpose**: Provide broadcast-style messaging (publish/subscribe) on top of a Redis-compatible store (Valkey) and an in-memory queue for TypeScript apps (especially Mercurius GraphQL).

##### File Structure
- **Top-level files**:
- `package.json`, `README.md`, `LICENSE`, CI workflows → project metadata and pipelines.
- `__tests__` → Jest tests validating core behaviors.
- **`src/`**:
- `index.ts` → entry point, exports `ValkeyPubSub` and `PubSubGenericQueue`.
- `ValkeyPubSub.ts` → implements Redis-backed pub/sub.
- `PubSubGenericQueue.ts` → in-memory queue for message buffering and delivery.
- **Configs**:
- TypeScript (`tsconfig.*`) and Jest (`jest.config.mjs`) → build/test tooling.

##### README for Architecture Clues
- **Core components**:
- `ValkeyPubSub.create(config)` → instantiates a Valkey (Redis) client and sets up connections.
- `.publish({ topic, payload })` → stringifies and sends messages via Redis channels.
- `.subscribe(topic, queue)` → subscribes the Redis client to a channel and forwards incoming messages into a `PubSubGenericQueue`.
- `PubSubGenericQueue` → holds items in memory and invokes `.onItem()` callbacks for each new message.
- **External integration**:
- Designed to slot into Mercurius GraphQL for subscriptions.

##### Main Components (to include
a. **Client Application**
- E.g., a GraphQL server (Fastify + Mercurius) or any TypeScript process that uses this library.
b. **ValkeyPubSub**
- Manages one or more Redis connections (standalone or cluster).
- Implements `publish`, `subscribe`, and `cleanup`.
c. **Valkey (Redis-Compatible Store)**
- External service. Channels/topics live here.
- RESP2/RESP3 protocol.
d. **PubSubGenericQueue**
- In-memory queue; buffers messages and distributes to listeners via callback.
e. **Listeners / Subscribers**
- Application code consuming messages via `queue.onItem()`.

##### Relationships and Data Flows
- **Publish Flow**:
1) Client calls `ValkeyPubSub.publish({ topic, payload })`.
2) `ValkeyPubSub` stringifies and pushes the message into Redis under that `topic` channel.
3) Redis broadcasts to all subscribers on that channel.
- **Subscribe Flow**:
1) Client creates a `PubSubGenericQueue`.
2) Client calls `ValkeyPubSub.subscribe(topic, queue)`.
3) `ValkeyPubSub` issues a Redis SUBSCRIBE command for `topic`.
4) Upon receiving a message from Redis, `ValkeyPubSub` parses JSON and calls `queue.push(message)`.
5) `PubSubGenericQueue` emits the message to all registered `.onItem()` callbacks.
- **Cleanup**:
- `ValkeyPubSub.cleanup()` closes Redis connections.
- `queue.destroy()` tears down in-memory resources.

##### Architectural Patterns and Design Principles
- **Pub/Sub Messaging** over Redis channels for decoupled, broadcast delivery.
- **Queue Abstraction** hides transport details from listeners, enabling in-memory delivery and buffering.
- **Modular & Type-Safe**: each piece is its own TS module, tests in Jest, can be imported as CJS or ESM.
- **Extensibility**: You could swap out the queue for another implementation or point to a different Redis client.

##### Essential Elements
- Footnote: Configuration object passed into `ValkeyPubSub.create()` (addresses, protocol, clusterMode).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    ClientApp["Client Application"]:::app
    GraphQLServer["GraphQL Server"]:::app

    ClientApp -->|"uses"| GraphQLServer

    %% Library Module
    subgraph "valkey-pubsub Library"
        direction TB
        EntryPoint["Library Entry Point\n(exports ValkeyPubSub & PubSubGenericQueue)"]:::library
        ValkeyPubSub["ValkeyPubSub\n.create(), publish(), subscribe(), cleanup()"]:::library
        PubSubGenericQueue["PubSubGenericQueue\n.push(), onItem(), destroy()"]:::library
    end

    GraphQLServer -->|"imports"| EntryPoint
    EntryPoint -->|"provides"| ValkeyPubSub
    EntryPoint -->|"provides"| PubSubGenericQueue

    %% Redis External Service
    Redis["Valkey (Redis-Compatible Store)"]:::external

    %% Publish Flow
    ValkeyPubSub -->|"PUBLISH(topic,payload)"| Redis
    Redis -->|"broadcast to subscribers"| ValkeyPubSub

    %% Subscribe Flow
    ValkeyPubSub -->|"SUBSCRIBE(topic)"| Redis
    Redis -->|"message received"| ValkeyPubSub
    ValkeyPubSub -->|"parse JSON\npush(payload)"| PubSubGenericQueue
    PubSubGenericQueue -->|"callback(payload)"| Listener

    Listener["Subscriber Listener\n(onItem() callback)"]:::app

    %% Project Files & Configs
    subgraph "Project Files & Configs"
        direction TB
        PackageJSON["package.json"]:::files
        README["README.md"]:::files
        License["LICENSE"]:::files
        CI1[".github/workflows/ci.yml"]:::files
        CI2[".github/workflows/publish.yml"]:::files
        JestConfig["jest.config.mjs"]:::files
        TSConfig1["tsconfig.json"]:::files
        TSConfig2["tsconfig.cjs.json"]:::files
        TSConfig3["tsconfig.esm.json"]:::files
    end

    %% Tests
    subgraph "Unit Tests"
        direction TB
        VPTests["valkey-pubsub.test.ts"]:::files
        PGQTests["pub-sub-generic-queue.test.ts"]:::files
    end

    %% Click Events
    click ValkeyPubSub "https://github.com/cbschuld/valkey-pubsub/blob/main/src/ValkeyPubSub.ts"
    click PubSubGenericQueue "https://github.com/cbschuld/valkey-pubsub/blob/main/src/PubSubGenericQueue.ts"
    click EntryPoint "https://github.com/cbschuld/valkey-pubsub/blob/main/src/index.ts"
    click VPTests "https://github.com/cbschuld/valkey-pubsub/blob/main/__tests__/valkey-pubsub.test.ts"
    click PGQTests "https://github.com/cbschuld/valkey-pubsub/blob/main/__tests__/pub-sub-generic-queue.test.ts"
    click PackageJSON "https://github.com/cbschuld/valkey-pubsub/blob/main/package.json"
    click README "https://github.com/cbschuld/valkey-pubsub/blob/main/README.md"
    click License "https://github.com/cbschuld/valkey-pubsub/tree/main/LICENSE"
    click CI1 "https://github.com/cbschuld/valkey-pubsub/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/cbschuld/valkey-pubsub/blob/main/.github/workflows/publish.yml"
    click JestConfig "https://github.com/cbschuld/valkey-pubsub/blob/main/jest.config.mjs"
    click TSConfig1 "https://github.com/cbschuld/valkey-pubsub/blob/main/tsconfig.json"
    click TSConfig2 "https://github.com/cbschuld/valkey-pubsub/blob/main/tsconfig.cjs.json"
    click TSConfig3 "https://github.com/cbschuld/valkey-pubsub/blob/main/tsconfig.esm.json"

    %% Styles
    classDef app fill:#ffa500,stroke:#333,stroke-width:1px
    classDef library fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#add8e6,stroke:#333,stroke-width:1px
    classDef files fill:#f0f0f0,stroke:#666,stroke-width:1px,font-style:italic
```
