# graffish-labs/symfony-nats-transport architecture

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

- Interactive diagram: https://gitdiagram.com/graffish-labs/symfony-nats-transport
- Repository: https://github.com/graffish-labs/symfony-nats-transport

## Overview

##### Project type and purpose
- This is a Symfony Messenger transport bundle ("graffish-labs/symfony-nats-transport") that plugs into a Symfony application.
- Its purpose is to let the Symfony Messenger component publish and consume messages via a NATS server.

##### File structure
- Top level: composer files, config folder, src folder.
- config/services.yaml: service definitions for the bundle.
- src/DependencyInjection: bundle extension and configuration classes (loads user config, registers services).
- src/GraffishLabsSymfonyNatsTransportBundle.php: the Bundle class that hooks into Symfony’s DI.
- src/Transport: NatsTransportFactory (creates the transport), NatsTransport (implements sending/receiving via NATS), and a config bean.

##### README
- Confirms dependencies: PHP 8.1+, Symfony 6+, Messenger 7.2+, NATS server.
- Lists features: reconnection logic, serialization (using Symfony Serializer), support for retries/failures.

a. Main components
- Symfony Application (FrameworkBundle, Messenger)
- GraffishLabsSymfonyNatsTransportBundle (Bundle class, DI Extension, Configuration)
- NatsTransportFactory
- NatsTransport
- Symfony Serializer component
- NATS Server (external)
- MessageBus (async transport layer)
- User-defined message handlers (inside the Symfony app)

b. Relationships & interactions
1. At boot: Bundle class registers DependencyInjection Extension → loads config/services.yaml → registers NatsTransportFactory and NatsTransport as messenger transports.
2. When you configure messenger.yaml with “nats://…”: Messenger asks the TransportFactory to create a NatsTransport instance.
3. NatsTransport uses the Symfony Serializer to turn your Message objects into bytes.
4. Publish flow: MessageBus → MessengerTransport (NatsTransport) → NATS Server (Pub).
5. Subscribe flow: NatsTransport opens subscription to NATS Server → receives messages → uses Serializer to decode → dispatches to MessageBus → handlers.
6. Retry/Failure: on exception, messenger retry/failure transports engage per Symfony Messenger policies.

c. Architectural patterns & design principles
- Dependency Injection (bundle extension registers services)
- Factory pattern (NatsTransportFactory)
- Adapter pattern (NatsTransport adapts NATS client to Symfony Messenger TransportInterface)
- Plugin/Bundle architecture (integrates into Symfony via Bundle class)

d. Key technologies & libraries
- Symfony Framework & Messenger component
- PHP 8.1 types and attributes
- Symfony Serializer (for message payloads)
- NATS PHP client (under the hood in NatsTransport)
- YAML configuration

##### Elements
- Blue rectangles for core Symfony components
- Green rectangles for bundle/DI classes
- Orange circle for external NATS Server
- Clear callouts for configuration: service definitions in config/services.yaml and messenger.yaml.

- Layer 1 (Configuration & Boot): Bundle class & DependencyInjection → registers factory & transport.
- Layer 2 (Factory & DI): NatsTransportFactory reads DSN & options → instantiates NatsTransport + Serializer.
- Layer 3 (Transport): NatsTransport implements TransportInterface; manages connection to NATS, reconnection logic, subscribes/publishes.
- Layer 4 (External): NATS Server as message broker.
- Layer 5 (Runtime Flow): MessageBus → Transport → NATS → Transport → MessageBus → Handlers

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layer 1: Configuration & Boot
    subgraph "Layer 1: Configuration & Boot"
        Composer["composer.json"] 
        Bundle["GraffishLabsSymfonyNatsTransportBundle"] 
        Extension["DependencyInjection Extension"] 
        Config["Bundle Configuration"] 
        Services["Service Definitions (services.yaml)"]
    end

    %% Layer 2: Factory & DI
    subgraph "Layer 2: Factory & DI"
        Factory["NatsTransportFactory"]
    end

    %% Layer 3: Transport
    subgraph "Layer 3: Transport"
        Transport["NatsTransport"]
        Serializer["Symfony Serializer"]
    end

    %% Layer 4: External
    subgraph "Layer 4: External"
        NATS["NATS Server"]
    end

    %% Layer 5: Runtime Flow
    subgraph "Layer 5: Runtime Flow"
        MessageBus["MessageBus"]
        Handlers["User-defined Handlers"]
    end

    %% Connections
    Composer -->|"bundle registration"| Bundle
    Bundle -->|"registers extension"| Extension
    Extension -->|"loads config"| Services
    Extension -->|"loads config definitions"| Config
    Extension -->|"registers factory service"| Factory

    MessageBus -->|"asks for transport via DSN"| Factory
    Factory -->|"instantiates transport + serializer"| Transport
    Transport -->|"uses"| Serializer

    %% Publish flow
    MessageBus -->|"publish message"| Transport
    Transport -->|"serialize payload"| Serializer
    Serializer -->|"bytes"| NATS

    %% Subscribe flow
    NATS -->|"message"| Transport
    Transport -->|"deserialize payload"| Serializer
    Serializer -->|"Message object"| MessageBus
    MessageBus -->|"dispatch to"| Handlers

    %% Retry/Failure (Symfony Messenger policies)
    Transport -- "on error" --> MessageBus

    %% Click Events
    click Bundle "https://github.com/graffish-labs/symfony-nats-transport/blob/main/src/GraffishLabsSymfonyNatsTransportBundle.php"
    click Extension "https://github.com/graffish-labs/symfony-nats-transport/blob/main/src/DependencyInjection/GraffishLabsSymfonyNatsTransportExtension.php"
    click Config "https://github.com/graffish-labs/symfony-nats-transport/blob/main/src/DependencyInjection/Configuration.php"
    click Services "https://github.com/graffish-labs/symfony-nats-transport/blob/main/config/services.yaml"
    click Factory "https://github.com/graffish-labs/symfony-nats-transport/blob/main/src/Transport/NatsTransportFactory.php"
    click Transport "https://github.com/graffish-labs/symfony-nats-transport/blob/main/src/Transport/NatsTransport.php"
    click Composer "https://github.com/graffish-labs/symfony-nats-transport/blob/main/composer.json"

    %% Styles
    classDef coreSym fill:#bbdefb,stroke:#000,stroke-width:1px
    classDef bundle fill:#c8e6c9,stroke:#000,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#000,stroke-width:1px
    classDef serializer fill:#d1c4e9,stroke:#000,stroke-width:1px

    class MessageBus,Handlers coreSym
    class Bundle,Extension,Config,Services,Factory,Transport bundle
    class NATS external
    class Serializer serializer
```
