# absmach/magistrala architecture

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

- Interactive diagram: https://gitdiagram.com/absmach/magistrala
- Repository: https://github.com/absmach/magistrala

## Overview

##### Main System Components

a) Client Layer:
- Multiple protocol endpoints (HTTP, MQTT, WebSocket, CoAP)
- Device connections and user interfaces
- Multi-tenant architecture

b) Gateway Layer:
- NGINX reverse proxy
- VerneMQ MQTT broker
- Protocol adapters

c) Core Services Layer:
- Bootstrap service (device provisioning)
- Authentication & Authorization (with Vault integration)
- Rules Engine (RE)
- Notification services (SMTP, SMPP)

d) Data Layer:
- PostgreSQL database
- TimescaleDB
- Redis cache
- NATS message broker

##### Specific Implementation Details

Key architectural elements:
- Authentication Flow
- mTLS certification path
- Access control (ABAC/RBAC)
- Message Flow
- Writers (postgres-writer, timescale-writer)
- Readers (postgres-reader, timescale-reader)
- Event sourcing pattern
- Monitoring Stack
- Prometheus metrics
- OpenTelemetry tracing
- Logging infrastructure

##### Specific Implementation Notes

- The event-driven architecture using NATS
- The separation between readers and writers
- The security layer with Vault integration
- The scalability pattern with separate reader/writer services

##### Additional Elements

Include:
- Version compatibility information
- Deployment boundaries (if using microservices)
- Integration points for external systems

**┌─────────────────────────────────┐**
- Client Layer (Devices/Users)    │
- ┤
- Gateway Layer (NGINX/VerneMQ)   │
- ┤
- Core Services                   │
- ┤
- Data Layer                      │
- ┘

##### Critical Paths to Highlight

Emphasize:
- Device provisioning flow
- Message publication path
- Authentication/Authorization flow
- Rules engine processing path

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph Clients
        HTTP[HTTP Clients]
        MQTT[MQTT Clients]
        WS[WebSocket Clients]
        COAP[CoAP Clients]
    end

    %% Gateway Layer
    subgraph Gateway
        NGINX["NGINX Proxy"]:::infra
        VERNEMQ["VerneMQ Broker"]:::messagebroker
        ADAPTERS["Protocol Adapters"]:::service
    end
    click NGINX "https://github.com/absmach/magistrala/tree/main/docker/nginx/"
    click VERNEMQ "https://github.com/absmach/magistrala/tree/main/docker/vernemq/"

    %% Core Services Layer
    subgraph CoreServices
        AUTH["Authentication & Authorization"]:::security
        BOOTSTRAP["Bootstrap Service"]:::service
        RE["Rules Engine"]:::service
        PROVISION["Device Provisioning"]:::service
        
        subgraph Notifiers
            SMTP["SMTP Notifier"]:::service
            SMPP["SMPP Notifier"]:::service
        end
    end
    click AUTH "https://github.com/absmach/magistrala/tree/main/docker/ssl/"
    click BOOTSTRAP "https://github.com/absmach/magistrala/tree/main/bootstrap/"
    click RE "https://github.com/absmach/magistrala/tree/main/re/"
    click PROVISION "https://github.com/absmach/magistrala/tree/main/provision/"
    click SMTP "https://github.com/absmach/magistrala/tree/main/consumers/notifiers/smtp/"
    click SMPP "https://github.com/absmach/magistrala/tree/main/consumers/notifiers/smpp/"

    %% Data Layer
    subgraph DataLayer
        subgraph Writers
            PW["PostgreSQL Writer"]:::writer
            TW["TimescaleDB Writer"]:::writer
        end
        
        subgraph Readers
            PR["PostgreSQL Reader"]:::reader
            TR["TimescaleDB Reader"]:::reader
        end
        
        POSTGRES[(PostgreSQL)]:::database
        TIMESCALE[(TimescaleDB)]:::database
        REDIS[(Redis Cache)]:::cache
        NATS{"NATS Broker"}:::messagebroker
        VAULT["HashiCorp Vault"]:::security
    end
    click PW "https://github.com/absmach/magistrala/tree/main/consumers/writers/postgres/"
    click TW "https://github.com/absmach/magistrala/tree/main/consumers/writers/timescale/"
    click PR "https://github.com/absmach/magistrala/tree/main/readers/postgres/"
    click TR "https://github.com/absmach/magistrala/tree/main/readers/timescale/"
    click REDIS "https://github.com/absmach/magistrala/tree/main/internal/clients/redis/"
    click VAULT "https://github.com/absmach/magistrala/tree/main/docker/addons/vault/"

    %% Monitoring
    subgraph Monitoring
        PROM["Prometheus"]:::monitoring
    end
    click PROM "https://github.com/absmach/magistrala/tree/main/docker/addons/prometheus/"

    %% Relationships
    Clients --> NGINX
    NGINX --> VERNEMQ
    NGINX --> ADAPTERS
    VERNEMQ --> AUTH
    ADAPTERS --> AUTH
    AUTH --> VAULT
    AUTH --> REDIS
    BOOTSTRAP --> NATS
    RE --> NATS
    PROVISION --> NATS
    SMTP --> NATS
    SMPP --> NATS
    NATS --> Writers
    Writers --> POSTGRES
    Writers --> TIMESCALE
    Readers --> POSTGRES
    Readers --> TIMESCALE
    CoreServices --> PROM

    %% Styles
    classDef service fill:#3498db,stroke:#2980b9,color:white
    classDef security fill:#9b59b6,stroke:#8e44ad,color:white
    classDef database fill:#2ecc71,stroke:#27ae60,color:white
    classDef cache fill:#e74c3c,stroke:#c0392b,color:white
    classDef messagebroker fill:#e67e22,stroke:#d35400,color:white
    classDef infra fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef monitoring fill:#34495e,stroke:#2c3e50,color:white
    classDef writer fill:#16a085,stroke:#138a72,color:white
    classDef reader fill:#27ae60,stroke:#229954,color:white

    %% Legend
    subgraph Legend
        SVC["Service"]:::service
        SEC["Security Component"]:::security
        DB[(Database)]:::database
        CACHE[(Cache)]:::cache
        MB{"Message Broker"}:::messagebroker
        INFRA["Infrastructure"]:::infra
        MON["Monitoring"]:::monitoring
        W["Writer"]:::writer
        R["Reader"]:::reader
    end
```
