# algoan/pubsub architecture

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

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

## Overview

##### Main Components

a) Core Components:
- PubSubFactory (Central factory class)
- Abstract PubSub Interface
- Google Cloud PubSub Implementation
- Message Handling System

b) External Components:
- Google Cloud PubSub Service
- Client Applications

**Layer 1 (Client Interface):**
- PubSubFactory
- Configuration Options

**Layer 2 (Core Abstract Layer):**
- PubSub Interface
- EmittedMessage Interface

**Layer 3 (Implementation Layer):**
- GoogleCloudPubSub Implementation
- Extended Message Handling

**Layer 4 (External Services):**
- Google Cloud PubSub

##### Key Elements to Highlight

a) Message Flow:

b) Component Relationships:
- Factory pattern relationship between PubSubFactory and concrete implementations
- Interface implementation relationship between PubSub interface and GoogleCloudPubSub

##### Specific Implementation Details

- Message transformation and handling
- Auto-acknowledgment system
- Topic/Subscription prefix handling
- Error handling flow

##### Technical Details

- Supported message formats
- Configuration options
- Environment variables
- Debug options

**┌─ Client Usage Layer ─────────────────┐**
- PubSubFactory.create()              │
- Transport selection               │
- Configuration options             │
- Abstract Layer ───────────────────┐ │
- PubSub Interface                   │ │
- listen()                        │ │
- emit()                          │ │
- unsubscribe()                   │ │
- Implementation Layer ─────────────┤ │
- GoogleCloudPubSub                 │ │
- Topic management                │ │
- Subscription handling           │ │
- Message transformation          │ │
- External Services ────────────────┤ │
- Google Cloud PubSub              │ │
- Topics                         │ │
- Subscriptions                  │ │
- ┘ │

##### Additional Notes

- Version compatibility information
- Notes about extensibility for future transport implementations

This design should clearly communicate both the current implementation and the potential for extending the system with additional transport mechanisms in the future.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        CLI["Client Application"]
        PSF["PubSubFactory"]:::factory
        click PSF "https://github.com/algoan/pubsub/blob/master/src/PubSubFactory.ts"
    end

    subgraph "Abstract Layer"
        PSI["PubSub Interface"]:::interface
        EMI["EmittedMessage Interface"]:::interface
        click PSI "https://github.com/algoan/pubsub/blob/master/src/PubSub.ts"
        click EMI "https://github.com/algoan/pubsub/blob/master/src/EmittedMessage.ts"
    end

    subgraph "Implementation Layer"
        GCPS["GoogleCloudPubSub"]:::implementation
        EXM["Extended Message Handling"]:::implementation
        UTIL["Implementation Utilities"]:::implementation
        click GCPS "https://github.com/algoan/pubsub/blob/master/src/GoogleCloudPubSub/GoogleCloudPubSub.ts"
        click EXM "https://github.com/algoan/pubsub/blob/master/src/GoogleCloudPubSub/ExtendedMessage.ts"
        click UTIL "https://github.com/algoan/pubsub/blob/master/src/GoogleCloudPubSub/lib.ts"
    end

    subgraph "External Services"
        GCP["Google Cloud PubSub"]:::external
        TOPIC["Topics"]:::external
        SUB["Subscriptions"]:::external
    end

    subgraph "Testing & Examples"
        EX["Example Implementation"]:::example
        TEST["Implementation Tests"]:::test
        TUTIL["Test Utilities"]:::test
        click EX "https://github.com/algoan/pubsub/blob/master/examples/google-pubsub/index.js"
        click TEST "https://github.com/algoan/pubsub/blob/master/test/GoogleCloudPubSub.test.ts"
        click TUTIL "https://github.com/algoan/pubsub/blob/master/test/utils/test-utils.ts"
    end

    %% Relationships
    CLI --> PSF
    PSF --> PSI
    PSI --> EMI
    PSI --> GCPS
    GCPS --> EXM
    GCPS --> UTIL
    GCPS --> GCP
    GCP --> TOPIC
    GCP --> SUB
    EX -.-> PSF
    TEST -.-> GCPS
    TEST -.-> TUTIL

    %% Message Flow
    EmitFlow["Emit Path"]:::flow
    ListenFlow["Listen Path"]:::flow
    CLI --> EmitFlow
    EmitFlow --> PSF
    EmitFlow --> GCPS
    EmitFlow --> GCP
    GCP --> ListenFlow
    ListenFlow --> GCPS
    ListenFlow --> CLI

    classDef interface fill:#2196F3,stroke:#1565C0,color:white
    classDef implementation fill:#4CAF50,stroke:#2E7D32,color:white
    classDef external fill:#9E9E9E,stroke:#616161,color:white
    classDef factory fill:#FF9800,stroke:#F57C00,color:white
    classDef flow fill:#E91E63,stroke:#C2185B,color:white
    classDef example fill:#673AB7,stroke:#512DA8,color:white
    classDef test fill:#795548,stroke:#5D4037,color:white

    %% Legend
    subgraph Legend
        L1["Interface"]:::interface
        L2["Implementation"]:::implementation
        L3["External Service"]:::external
        L4["Factory"]:::factory
        L5["Message Flow"]:::flow
        L6["Example/Test"]:::example
    end
```
