# truenas/middleware architecture

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

- Interactive diagram: https://gitdiagram.com/truenas/middleware
- Repository: https://github.com/truenas/middleware

## Overview

##### Main System Components

a) Frontend Layer:
- Web UI interface
- REST API endpoints
- WebSocket interface
- CLI interface

b) Middleware Layer (Core):
- Middleware daemon (main service orchestrator)
- Event system
- Job queue system
- Authentication/Authorization
- Plugin system
- Database layer (SQLAlchemy)

c) Service Layer:
- Storage services (ZFS, disk management)
- Sharing services (SMB, NFS, iSCSI)
- Directory services (Active Directory, LDAP)
- System services (Updates, Network, etc.)
- Virtualization (VM management)
- Container services (Docker, apps)

d) Hardware Layer:
- Disk subsystem
- Network interfaces
- Hardware monitoring

##### Key Relationships to Highlight

- Client requests flow from Frontend → Middleware → Services
- Event propagation from Services → Middleware → Frontend
- Database interactions between Middleware and SQLite storage
- Authentication flow between components
- Hardware monitoring data flow

##### Special Architectural Elements

Important architectural patterns:
- Plugin-based architecture for extensibility
- Event-driven communication system
- Job queue for async operations
- Role-based access control
- API versioning system

##### Component Details

For each major component, include:
- Component name
- Key responsibilities
- Critical dependencies
- API endpoints (if applicable)
- Configuration files location

##### Specific Implementation Notes

TrueNAS-specific elements:
- Middleware daemon architecture
- Plugin system structure
- Alert system
- Audit framework
- Failover mechanism (for Enterprise)
- Container management system

##### Technical Details

- Database schema references
- Configuration file locations
- Service dependencies
- API versioning scheme
- Plugin extension points

- Layered architecture representation
- Clear connection lines
- Export to high-resolution formats

Remember to:
- Use consistent naming conventions
- Provide enough detail while maintaining clarity
- Version information
- Document all custom symbols or notations

This system design should accurately represent the complex nature of the TrueNAS system while remaining understandable to technical staff.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef frontend fill:#FFE873
    classDef middleware fill:#4B8BBE
    classDef service fill:#306998
    classDef hardware fill:#646464
    classDef security fill:#9B59B6
    classDef storage fill:#2ECC71
    classDef network fill:#E67E22

    %% Frontend Layer
    subgraph Frontend
        WebUI["Web UI Interface"]:::frontend
        REST["REST/WebSocket API"]:::frontend
        CLI["CLI Interface"]:::frontend
    end
    click REST "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/api/"

    %% Middleware Core Layer
    subgraph MiddlewareCore
        MWCore["Middleware Daemon"]:::middleware
        EventSys["Event System"]:::middleware
        JobQueue["Job Queue"]:::middleware
        Auth["Authentication"]:::security
        PluginSys["Plugin System"]:::middleware
        DB["Database Layer"]:::middleware
        AlertSys["Alert System"]:::middleware
        Schema["Schema System"]:::middleware
    end
    click MWCore "https://github.com/truenas/middleware/blob/master/src/middlewared/middlewared/main.py"
    click EventSys "https://github.com/truenas/middleware/blob/master/src/middlewared/middlewared/event.py"
    click JobQueue "https://github.com/truenas/middleware/blob/master/src/middlewared/middlewared/job.py"
    click Auth "https://github.com/truenas/middleware/blob/master/src/middlewared/middlewared/auth.py"
    click PluginSys "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/plugins/"
    click DB "https://github.com/truenas/middleware/blob/master/src/middlewared/middlewared/sqlalchemy.py"
    click AlertSys "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/alert/"
    click Schema "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/schema/"

    %% Service Layer
    subgraph Services
        StorageServ["Storage Services"]:::storage
        SharingServ["Sharing Services"]:::network
        DirServ["Directory Services"]:::network
        SysServ["System Services"]:::service
        VMServ["Virtualization Services"]:::service
        ContainerServ["Container Services"]:::service
    end
    click StorageServ "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/plugins/pool_/"
    click SharingServ "https://github.com/truenas/middleware/blob/master/src/middlewared/middlewared/plugins/smb.py"
    click DirServ "https://github.com/truenas/middleware/blob/master/src/middlewared/middlewared/plugins/directoryservices.py"
    click SysServ "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/plugins/system/"
    click VMServ "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/plugins/vm/"
    click ContainerServ "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/plugins/docker/"

    %% Hardware Layer
    subgraph Hardware
        DiskSys["Disk Subsystem"]:::hardware
        NetInt["Network Interfaces"]:::hardware
        HWMon["Hardware Monitoring"]:::hardware
    end
    click DiskSys "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/plugins/disk_/"
    click NetInt "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/plugins/interface/"
    click HWMon "https://github.com/truenas/middleware/tree/master/src/middlewared/middlewared/plugins/hardware/"

    %% Connections
    WebUI --> REST
    CLI --> REST
    REST --> MWCore
    MWCore --> EventSys
    MWCore --> JobQueue
    MWCore --> Auth
    MWCore --> PluginSys
    MWCore --> DB
    MWCore --> AlertSys
    MWCore --> Schema
    
    EventSys --> Services
    JobQueue --> Services
    PluginSys --> Services
    
    Services --> DiskSys
    Services --> NetInt
    Services --> HWMon
    
    %% Legend
    subgraph Legend
        Frontend_L["Frontend Components"]:::frontend
        Middleware_L["Middleware Components"]:::middleware
        Service_L["Service Components"]:::service
        Hardware_L["Hardware Components"]:::hardware
        Security_L["Security Components"]:::security
        Storage_L["Storage Components"]:::storage
        Network_L["Network Components"]:::network
    end
```
