# linux-automation/tacd architecture

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

- Interactive diagram: https://gitdiagram.com/linux-automation/tacd
- Repository: https://github.com/linux-automation/tacd

## Overview

##### Project type and purpose
- This is a full-stack embedded application:
- A Rust-based monolithic “tacd” daemon running on the LXA-TAC hardware
- A React-based web UI (in web/) that interacts with the daemon via HTTP and MQTT
- A local UI on the TAC’s LCD screen
- Purpose: Bridge between hardware (ADC, GPIO, displays, power regulators, etc.) and users via a local display and a web/API interface.

##### File structure for architectural components
- Top level:
- src/: the Rust application (“tacd”)
- openapi.yaml: API specification
- demo_files/: reference file layout for embedded runs
- web/: front-end React application
- src/ modules:
- Hardware interfaces (adc.rs, digital_io.rs, backlight.rs, usb_hub.rs, watchdog.rs, temperatures.rs, regulators.rs, etc.)
- broker/: MQTT and REST broker
- http_server/: static file serving & API endpoints
- dbus/: interaction with system services (systemd, networkmanager, hostnamed, rauc)
- ui/: local LCD UI screens, widgets, display driver
- journal.rs: persistent event logging
- watched_tasks.rs: supervisory task runner
- main.rs / system.rs: application entrypoint and orchestration
- web/:
- public/: built assets (index.html, manifest.json)
- src/: TypeScript/React components fetching from HTTP API or MQTT, rendering dashboard, config editors, etc.

##### README for additional insights
- The daemon supports a “demo_mode” feature flag to stub hardware modules
- Build instructions show separation between host PC (demo_mode) and cross-compiled embedded targets
- The web UI is built independently via npm, output is bundled into the daemon binary

##### Main components
1. Hardware Layer (LXA TAC)
- ADC sensors, GPIO lines, USB hub, backlight, power regulators, temperature sensors, watchdog
2. tacd Daemon (Rust)
- Hardware Abstraction Modules
- System Core / Task Scheduler (watched_tasks)
- Persistence (journal → state.json)
- DBus Client Subsystem (systemd, networkmanager, hostnamed, rauc)
- Broker Subsystem (MQTT + REST)
- HTTP Server (serves web frontend + OpenAPI endpoints)
- Local UI Module (drives LCD via ui/ screens)
3. Frontends
- Local Display UI (LCD)
- Web UI (React app, served static → communicates over HTTP & optionally WebSocket/MQTT)
- External API clients (scripts, labgrid integration via REST/MQTT)
4. External Services
- MQTT clients/brokers (for remote scripting or monitoring)
- D-Bus system services (systemd, networkmanager, rauc)
- Labgrid environment (from demo_files)

##### Relationships and interactions
- Hardware → tacd hardware modules (via libiio, GPIO sysfs, etc.)
- tacd system core → schedules modules, reads sensors, writes actuators
- Hardware events & system state → published to:
- Local UI (ui/ screens)
- Broker → MQTT topics + REST endpoints
- Journal → state.json
- HTTP Server:
- Serves static React assets
- Exposes OpenAPI endpoints for status, control
- React Web UI ↔ HTTP Server (REST calls)
- React Web UI ↔ MQTT Broker (real-time updates)
- tacd → D-Bus services for system config, updates, networking

##### Architectural patterns and design principles
- Modular monolith: clearly separated sub-packages, all compiled into one binary
- Feature flags: “demo_mode” for host-side stubs
- Event-driven / pub-sub internally: hardware events → broker → UIs
- Clear separation between hardware abstraction, core logic, persistence, and presentation layers

##### Essential elements
- Annotations for feature flags (demo_mode) and cross-compilation target

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        ADC["ADC Sensors"]:::hardware
        GPIO["GPIO / Digital I/O"]:::hardware
        USBHub["USB Hub"]:::hardware
        Backlight["Backlight"]:::hardware
        Regulators["Power Regulators"]:::hardware
        Temps["Temperature Sensors"]:::hardware
        Watchdog["Watchdog Timer"]:::hardware
        DUTPower["DUT Power Control"]:::hardware
    end

    %% tacd Daemon
    subgraph "tacd Daemon"
        direction TB
        Entry["Entry & Orchestration"]:::backend
        Scheduler["Task Scheduler / Supervisor"]:::backend
        Journal["Persistence / Event Journal"]:::backend
        DBus["D-Bus Client Subsystem"]:::backend
        Broker["Broker Subsystem"]:::backend
        HTTP["HTTP Server"]:::backend
        LocalUI["Local UI Module"]:::backend
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        LocalDisplay["Local Display UI"]:::presentation
        WebUI["Web UI (React)"]:::presentation
        APIClients["External API Clients"]:::presentation
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MQTTBroker["MQTT Broker"]:::external
        DbusServices["System D-Bus Services"]:::external
        Labgrid["Labgrid Environment"]:::external
        DemoFiles["Demo Mode Files"]:::external
    end

    %% Connections
    ADC -->|GPIO sysfs / libiio| Entry
    GPIO -->|GPIO sysfs| Entry
    USBHub -->|USB API| Entry
    Backlight -->|PWM / I2C| Entry
    Regulators -->|I2C| Entry
    Temps -->|I2C| Entry
    Watchdog -->|Device File| Entry
    DUTPower -->|GPIO| Entry

    Entry -->|orchestrates| Scheduler
    Scheduler -->|logs events to| Journal
    Entry -->|invokes| DBus
    Entry -->|publishes events to| Broker
    Entry -->|serves assets via| HTTP
    Entry -->|drives| LocalUI

    Broker -->|MQTT| MQTTBroker
    Broker -->|REST| APIClients
    HTTP -->|HTTP/REST| WebUI
    MQTTBroker -->|MQTT| WebUI
    LocalUI -->|LCD Driver| LocalDisplay
    DBus <-->|"D-Bus"| DbusServices
    APIClients -->|REST/MQTT| Entry
    DemoFiles -.->|demo_mode data| Entry
    Labgrid -->|integration| Broker

    %% Click Events
    click ADC "https://github.com/linux-automation/tacd/blob/main/src/adc.rs"
    click GPIO "https://github.com/linux-automation/tacd/blob/main/src/digital_io.rs"
    click USBHub "https://github.com/linux-automation/tacd/blob/main/src/usb_hub.rs"
    click Backlight "https://github.com/linux-automation/tacd/blob/main/src/backlight.rs"
    click Regulators "https://github.com/linux-automation/tacd/blob/main/src/regulators.rs"
    click Temps "https://github.com/linux-automation/tacd/blob/main/src/temperatures.rs"
    click Watchdog "https://github.com/linux-automation/tacd/blob/main/src/watchdog.rs"
    click DUTPower "https://github.com/linux-automation/tacd/blob/main/src/dut_power.rs"
    click Entry "https://github.com/linux-automation/tacd/blob/main/src/main.rs"
    click Scheduler "https://github.com/linux-automation/tacd/blob/main/src/watched_tasks.rs"
    click Journal "https://github.com/linux-automation/tacd/blob/main/src/journal.rs"
    click DBus "https://github.com/linux-automation/tacd/blob/main/src/dbus.rs"
    click Broker "https://github.com/linux-automation/tacd/blob/main/src/broker.rs"
    click HTTP "https://github.com/linux-automation/tacd/blob/main/src/http_server.rs"
    click LocalUI "https://github.com/linux-automation/tacd/blob/main/src/ui.rs"
    click WebUI "https://github.com/linux-automation/tacd/blob/main/web/src/App.tsx"
    click DemoFiles "https://github.com/linux-automation/tacd/tree/main/demo_files/"

    %% Styles
    classDef hardware fill:#bbbbbb,stroke:#333,stroke-width:1px
    classDef backend fill:#aaccff,stroke:#036,stroke-width:1px
    classDef presentation fill:#ccffcc,stroke:#070,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#932,stroke-width:1px
```
