# nerves-hub/nerves_hub_web architecture

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

- Interactive diagram: https://gitdiagram.com/nerves-hub/nerves_hub_web
- Repository: https://github.com/nerves-hub/nerves_hub_web

## Overview

##### Main Components
- Application Server: At the heart is a Phoenix/Elixir application that handles web requests, API calls, and real-time communication (via channels). This is represented by directories such as lib/nerves_hub_web (web controllers, views, templates, channels, live views) and lib/nerves_hub (business logic modules like accounts, devices, deployments, firmware, audit logs, etc.).
- API and Web UI Layer: The controllers, live views, and channels expose both REST and real-time interfaces (for instance, the console and device channels found in lib/nerves_hub_web/channels).
- Background Processing: Several worker modules and Oban (background job queue) integrations are present in lib/nerves_hub/workers. These handle tasks like firmware delta building, device health truncation, and deployment processing.
- Data Persistence: Database integration (using Ecto and the Postgres database) is indicated by the priv/repo and migration files. This layer stores user accounts, device records, deployment information, logs, and audit trails.
- Firmware Storage & Upload: Modules related to firmware uploads (e.g., lib/nerves_hub/firmwares/upload with options for S3 and file transfers) indicate a dedicated component for managing and storing firmware images.
- Asset Management: A clear separation exists for frontend asset management (assets directory) which includes JavaScript, CSS, configuration files (Tailwind, eslint) and even modern UI improvements under assets/ui-rework.
- Security & Authentication: The project uses certificate handling (modules under lib/nerves_hub/devices, lib/nerves_hub/accounts) to secure device communication and shared secret authentication for simplified onboarding.

##### Establish Relationships and Data Flow
- Clients (e.g., devices, web browsers, APIs) interacting with the Phoenix server.
- Real-time channels: indicate separate directional flows between the device channels (for live debugging, console data) and the central application server.
- Background job processing where requests trigger asynchronous tasks (worker modules processing firmware deltas, device health updates, etc.).

##### Architectural Patterns and Design Principles
- MVC and LiveView Pattern: The clear division between controllers, views/templates, and live views suggests an MVC pattern enriched by real-time reactivity through LiveView.
- Domain-Driven Decomposition: With modules clearly separated into “accounts,” “devices,” “deployments,” and “firmwares,” the design follows a domain-centric structure.
- Containerization & Deployment: Presence of Dockerfile and docker-compose.yml indicate the application is designed for containerized deployment. Additionally, environment-specific config files (config/prod.exs, dev.exs, runtime.exs) encompass environment-dependent configurations.
- Use of background job frameworks like Oban is a key design element for reliability and scaling, ensuring long-running processes do not block synchronous flows.

##### Technologies, Frameworks, and Libraries
- Elixir & Phoenix: The core application framework.
- Ecto & PostgreSQL: For data persistence and repository management.
- Oban/Background Workers: For asynchronous task processing.
- Webpack, Tailwind, and other NodeJS-based asset tools: Found in the assets directory.
- Containerization (Docker, docker-compose) for deployment.
- Erlang/OTP: Supported by configuration and dependency tools (.tool-versions).

##### Specific Elements
- Clear labels for each component (e.g., “Web Interface (Phoenix Controllers & LiveViews)”, “API Gateway”, “Background Workers/Oban”, “Postgres DB”, “Firmware Storage (S3)”, “Device Channels”).
- User and device requests entering through a load balancer or web server.
- To the API endpoints/components.
- Data flow to/from the database and storage.
- Optionally, a side note on integration points (e.g., container orchestration, SSL configuration, and environment-specific customizations).

##### Abstraction vs. Detail
- Avoid clutter by grouping related modules into “domains” such as Accounts, Devices, Deployments, and Firmware management.
- Use callouts or annotations for critical processes like firmware signing, deployment orchestration, and device authentication.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Presentation Layer
  subgraph "Presentation Layer"
    A["Web/API Gateway (Phoenix Endpoint)"]:::web
  end

  %% Business Logic Layer
  subgraph "Business Logic Layer"
    B["Application Core"]:::core
  end

  %% Persistence Layer
  subgraph "Persistence Layer"
    C["Repo Module"]:::db
    D["Migrations & Seeds"]:::db
  end

  %% Auxiliary Services
  subgraph "Auxiliary Services"
    E["Object Storage (S3)"]:::storage
    F["Background Workers"]:::workers
  end

  %% External Authentication/SSL Infrastructure
  subgraph "External Authentication/SSL"
    G["Certificate Management"]:::external
    H["SSL Handling"]:::external
  end

  %% Connections between layers
  A --> B
  B --> C
  B --> E
  F --> B
  F --> C
  B --> G
  B --> H

  %% Legend
  subgraph Legend [Legend]
    WL["Web/API Gateway - Blue"]:::web
    BL["Application Core - Green"]:::core
    PL["Persistence Layer - Yellow"]:::db
    SL["Object Storage - Purple"]:::storage
    BW["Background Workers - Orange"]:::workers
    EXL["External Auth/SSL - Red"]:::external
  end

  %% Click events
  click A "https://github.com/nerves-hub/nerves_hub_web/blob/main/lib/nerves_hub_web/endpoint.ex"
  click B "https://github.com/nerves-hub/nerves_hub_web/tree/main/lib/nerves_hub"
  click C "https://github.com/nerves-hub/nerves_hub_web/blob/main/lib/nerves_hub/repo.ex"
  click D "https://github.com/nerves-hub/nerves_hub_web/tree/main/priv/repo"
  click E "https://github.com/nerves-hub/nerves_hub_web/blob/main/lib/nerves_hub/firmwares/upload/s3.ex"
  click F "https://github.com/nerves-hub/nerves_hub_web/tree/main/lib/nerves_hub/workers"
  click G "https://github.com/nerves-hub/nerves_hub_web/blob/main/lib/nerves_hub/certificate.ex"
  click H "https://github.com/nerves-hub/nerves_hub_web/blob/main/lib/nerves_hub/ssl.ex"

  %% Classes
  classDef web fill:#add8e6,stroke:#000,stroke-width:2px;
  classDef core fill:#90ee90,stroke:#000,stroke-width:2px;
  classDef db fill:#ffff99,stroke:#000,stroke-width:2px;
  classDef storage fill:#dda0dd,stroke:#000,stroke-width:2px;
  classDef workers fill:#ffcc99,stroke:#000,stroke-width:2px;
  classDef external fill:#ff9999,stroke:#000,stroke-width:2px;
```
