# amrc-factoryplus/amrc-connectivity-stack architecture

> Architecture diagram of the GitHub repository amrc-factoryplus/amrc-connectivity-stack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amrc-factoryplus/amrc-connectivity-stack
- Repository: https://github.com/amrc-factoryplus/amrc-connectivity-stack

## Overview

##### Project Type and Purpose
- This is a distributed, microservices-based deployment designed to run on Kubernetes. Its purpose is to provide the complete connectivity stack for industrial edge management and device connectivity as part of the Factory+ framework.
- The system includes UI components (such as acs-admin built with Vue.js), authentication and identity services (acs-auth, acs-identity), device, configuration, and cluster management services (acs-configdb, acs-cluster-manager, acs-directory), edge-related components (acs-edge, acs-edge-sync, edge agent/driver projects), and other supporting services (acs-git, acs-mqtt, acs-service-setup, acs-visualiser, etc.).
- Helm charts and Kubernetes deployment artifacts (the deploy folder) indicating that the entire stack is deployed into a Kubernetes cluster and managed via Helm.

##### Analyzing the File Tree and Architectural Patterns
- Components by their roles: For instance, front-end UI (acs-admin), authentication (acs-auth, acs-krb-keys-operator), management microservices (acs-manager), and peripheral support such as monitoring (acs-monitor), git services (acs-git), and historical data ingest (historian-sparkplug, historian-uns).
- The presence of Dockerfiles, Kubernetes YAMLs/Helm charts, Makefiles and CI/CD pipelines (under .github) suggests containerized microservices with automated deployment.
- The structure suggests a microservices architecture with a clear separation of concerns. Each service has its own codebase, Docker configuration and sometimes even dedicated databases (via migrations and SQL directories).

##### Key Components and Their Relationships
a. Core Services:
– acs-admin: The front-end administrative application (Vue.js based) that interacts with several backend services.
– acs-auth and acs-identity: Handle authentication, authorization, and user identity elements.
– acs-manager: A central orchestration service handling devices, nodes, edge clusters, preferences, schemas, etc.
– acs-configdb and acs-directory: Likely responsible for configuration and managing directory data.
b. Edge-Specific Components:
– acs-edge, acs-edge-sync: Handling edge device connectivity and synchronization.
– Other edge drivers (e.g., edge-modbus, edge-openprotocol, edge-tplink-smartplug, etc.) that help connect various industrial protocols/devices.
– Edge Helm charts: “edge-helm-charts” for deploying edge agents and clusters.
c. Support & Infrastructure:
– acs-git: Internal Git server providing version control for configurations, potentially integrated with CI/CD.
– acs-mqtt: Likely handles messaging protocols (MQTT) for device communication.
– acs-krb-keys-operator, hivemq-krb, and associated Kerberos components, which deal with secure authentication and potentially key management.
– Monitoring components: acs-monitor for both centralized and edge monitoring.
– Historical/Telemetry Data: historian-sparkplug and historian-uns components for ingesting, processing, or visualizing historical data.
d. Deployment and Configuration:
– The deploy folder contains Helm templates and Kubernetes manifests, so showing a “Deployment/Orchestration Layer” that automates the rollout of the services.
– The shared base images in acs-base-images indicate standardization of container environments.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Deployment/Infrastructure Layer
    subgraph "Deployment/Infrastructure"
        Deployment["Deployment/Orchestration Layer (Helm Charts & Kubernetes Manifests)"]
        EdgeHelm["Edge Helm Charts (Edge Deployment)"]
        BaseImages["Base Container Images (ACS Base Images)"]
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        %% Presentation Layer
        A_Admin["ACS Admin (Frontend UI)"]
        
        %% Business/Service Layer
        A_Auth["ACS Auth (Authentication Service)"]
        A_Identity["ACS Identity (User Identity Service)"]
        A_Manager["ACS Manager (Orchestration & Device Management)"]
        A_ConfigDB["ACS ConfigDB (Configuration Database Service)"]
        A_Directory["ACS Directory (Directory Data Management)"]

        %% Edge and Device Connectivity Layer
        A_Edge["ACS Edge (Edge Device Connectivity Service)"]
        A_EdgeSync["ACS Edge-Sync (Edge Synchronization Service)"]
        EdgeBacnet["Edge Device Driver: Bacnet"]
        EdgeModbus["Edge Device Driver: Modbus"]
        EdgeOpenprotocol["Edge Device Driver: OpenProtocol"]
        EdgeTplink["Edge Device Driver: TP-Link Smartplug"]
        EdgeTest["Edge Device Driver: Test"]

        %% Messaging & Integration Layer
        A_MQTT["ACS MQTT (Messaging & MQTT Service)"]
        A_Git["ACS Git (Internal Git Service)"]
        A_Krb["ACS KRb Keys Operator (Kerberos Keys & Authentication Management)"]
        A_ServiceSetup["ACS Service Setup (Service Configuration & Setup)"]
        A_Visualiser["ACS Visualiser (Visualization Dashboard)"]

        %% Monitoring Layer
        A_Monitor["ACS Monitor (Monitoring Service)"]
        HistorianSpark["Historian Service: Sparkplug"]
        HistorianUns["Historian Service: UNS"]
    end

    %% Internal Service Communications
    A_Admin -->|"calls"| A_Manager
    A_Admin -->|"authenticates_with"| A_Auth
    A_Admin -->|"fetches_user_data"| A_Identity

    A_Manager -->|"retrieves_config_from"| A_ConfigDB
    A_Manager -->|"retrieves_directory_data_from"| A_Directory
    A_Manager -->|"manages_edge"| A_Edge
    A_Manager -->|"syncs_edge"| A_EdgeSync
    A_Manager -->|"triggers_git_ops"| A_Git
    A_Manager -->|"configured_by"| A_ServiceSetup
    A_Manager -->|"data_visualized_in"| A_Visualiser
    A_Manager -->|"monitored_by"| A_Monitor

    A_Edge -->|"communicates_with"| EdgeBacnet
    A_Edge -->|"communicates_with"| EdgeModbus
    A_Edge -->|"communicates_with"| EdgeOpenprotocol
    A_Edge -->|"communicates_with"| EdgeTplink
    A_Edge -->|"communicates_with"| EdgeTest
    A_Edge -->|"mqtt_comm"| A_MQTT

    A_Auth -->|"uses_keys_from"| A_Krb

    A_Edge -->|"monitored_by"| A_Monitor

    A_Monitor -->|"telemetry_to"| HistorianSpark
    A_Monitor -->|"telemetry_to"| HistorianUns

    %% Deployment Connections
    Deployment -->|"deploys"| A_Admin
    Deployment -->|"deploys"| A_Manager
    Deployment -->|"deploys"| A_Edge
    Deployment -->|"deploys"| A_MQTT
    Deployment -->|"deploys"| A_Monitor

    EdgeHelm -->|"deploys_edge_services"| A_EdgeSync
    EdgeHelm -->|"deploys_edge_drivers"| A_Edge

    BaseImages -->|"provides_base_for"| A_Admin
    BaseImages -->|"provides_base_for"| A_Manager

    %% Classes
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef edge fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef messaging fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef monitoring fill:#AFEEEE,stroke:#000,stroke-width:1px;
    classDef deployment fill:#D3D3D3,stroke:#000,stroke-width:1px;

    class A_Admin frontend;
    class A_Auth,A_Identity,A_Manager,A_ConfigDB,A_Directory backend;
    class A_Edge,A_EdgeSync,EdgeBacnet,EdgeModbus,EdgeOpenprotocol,EdgeTplink,EdgeTest edge;
    class A_MQTT,A_Git,A_Krb,A_ServiceSetup,A_Visualiser messaging;
    class A_Monitor,HistorianSpark,HistorianUns monitoring;
    class Deployment,EdgeHelm,BaseImages deployment;

    %% Click Events
    click A_Admin "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-admin"
    click A_Auth "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-auth"
    click A_Identity "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-identity"
    click A_Manager "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-manager"
    click A_ConfigDB "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-configdb"
    click A_Directory "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-directory"
    click A_Edge "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-edge"
    click A_EdgeSync "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-edge-sync"
    click EdgeBacnet "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/edge-bacnet"
    click EdgeModbus "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/edge-modbus"
    click EdgeOpenprotocol "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/edge-openprotocol"
    click EdgeTplink "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/edge-tplink-smartplug"
    click EdgeTest "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/edge-test"
    click A_Git "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-git"
    click A_MQTT "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-mqtt"
    click A_Krb "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-krb-keys-operator"
    click A_Monitor "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-monitor"
    click HistorianSpark "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/historian-sparkplug"
    click HistorianUns "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/historian-uns"
    click Deployment "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/deploy"
    click EdgeHelm "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/edge-helm-charts"
    click BaseImages "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-base-images"
    click A_ServiceSetup "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-service-setup"
    click A_Visualiser "https://github.com/amrc-factoryplus/amrc-connectivity-stack/tree/main/acs-visualiser"
```
