# aosedge/aos_common architecture

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

- Interactive diagram: https://gitdiagram.com/aosedge/aos_common
- Repository: https://github.com/aosedge/aos_common

## Overview

##### Main Components
- Common Infrastructure:
- Core packages like “aoserrors” (error handling) and “aostypes” (shared types).
- gRPC API and Protobuf Definitions:
- Under the “api” directory, you have separate submodules (cloudprotocol, communicationmanager, iamanager, servicemanager, updatemanager, visprotocol) that define the gRPC services and message contracts.
- That “api/common” contains generated protobuf Go files, which should be shown as part of the API layer.
- Specialized Functionality Modules:
- Modules handling system-level logic such as “image”, “journalalerts”, “migration”, “partition”, “resourcemonitor”, “spaceallocator”, and “tpmkey”.
- Client/Server Components:
- “iamclient” and the wsclient/wsserver packages serve as client and server implementations, likely used for communication with identity management or websocket interactions.
- Utility Libraries:
- The “utils” directory covers a wide variety of helper functionalities (for actions, alerts, file system operations, cryptographic operations, gRPC connection helpers, retry logic, semantic versioning, etc.). These are secondary components that support almost every aspect of the system.
- Build and CI/CD:

##### Relationships and Interactions
- API & gRPC Services:
- Library Usage:
- Derived packages such as “iamclient”, “wsclient”, and “wsserver” interact with the exposed APIs and common utilities for implementing business logic.
- Utilities Integration:
- Internal Components:
- The specialized modules (like resourcemonitor or spaceallocator) may also expose specific services or handle internal state changes that can be connected to the overall flows in the system.

##### Architectural Patterns & Design Principles
- Modular Design:
- The repository is clearly organized in a modular fashion, with dedicated directories for each area of responsibility.
- Interface-Based Communication:
- With its emphasis on gRPC and protobuf contracts, the design likely uses clear interface definitions to decouple service implementations.
- Reusability and Composability:
- The common utilities (within “utils” and the standalone packages) adhere to design principles that encourage reusability across different system components.

##### Relevant Technologies and Their Roles
- Go Language:
- The primary language of the project.
- gRPC & Protobuf:
- Used for defining service contracts (note the generate_api.sh script which is used to generate gRPC code from proto definitions).
- CI/CD Pipelines:
- GitHub Actions (.github/workflows) and GitLab CI (.gitlab-ci.yml) are used for continuous integration, testing, and quality control.
- Testing:
- Almost every module has accompanying _test.go files, indicating a strong focus on unit testing.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Common Infrastructure"
        AE["aoserrors"]:::common
        AT["aostypes"]:::common
    end

    subgraph "Utility Libraries"
        UT["Utils Library"]:::util
    end

    subgraph "gRPC API & Protobuf Definitions"
        CP["Cloud Protocol API"]:::api
        CM["Communication Manager API"]:::api
        IM["Identity Manager API"]:::api
        SM["Service Manager API"]:::api
        UM["Update Manager API"]:::api
        VP["Visualization Protocol API"]:::api
        GP["Common Protobuf Files"]:::api
    end

    subgraph "Specialized Modules"
        IMG["Image Handling"]:::special
        JA["Journal Alerts"]:::special
        MIG["Migration Logic"]:::special
        PM["Partition Management"]:::special
        RM["Resource Monitoring"]:::special
        SA["Space Allocator"]:::special
        TPM["TPM Key Processing"]:::special
    end

    subgraph "Client/Server Components"
        IAMC["IAM Client"]:::client
        WSC["Websocket Client"]:::client
        WSS["Websocket Server"]:::client
    end

    subgraph "CI/CD & Build"
        GH["GitHub Actions"]:::ci
        GL["GitLab CI"]:::ci
        CIS["CI Scripts"]:::ci
    end

    %% API components depend on common error handling
    CP -->|"uses"| AE
    CM -->|"uses"| AE
    IM -->|"uses"| AE
    SM -->|"uses"| AE
    UM -->|"uses"| AE
    VP -->|"uses"| AE
    GP -->|"uses"| AE

    %% Client calls to API
    IAMC -->|"calls"| IM
    WSC -->|"calls"| CM
    WSS -->|"calls"| SM

    %% Clients and specialized modules using utility libraries
    IAMC -->|"uses"| UT
    WSC -->|"uses"| UT
    WSS -->|"uses"| UT

    IMG -->|"uses"| UT
    JA  -->|"uses"| UT
    MIG -->|"uses"| UT
    PM  -->|"uses"| UT
    RM  -->|"uses"| UT
    SA  -->|"uses"| UT
    TPM -->|"uses"| UT

    %% Specialized module dependency on shared types
    IMG -->|"uses"| AT

    %% CI/CD triggers builds and tests on utilities
    GH  -->|"triggers"| UT
    GL  -->|"triggers"| UT
    CIS -->|"runs"| UT

    classDef common fill:#AED6F1,stroke:#000;
    classDef api fill:#A9DFBF,stroke:#000;
    classDef special fill:#F9E79F,stroke:#000;
    classDef client fill:#F5B7B1,stroke:#000;
    classDef util fill:#FAD7A0,stroke:#000;
    classDef ci fill:#D2B4DE,stroke:#000;

    click AE "https://github.com/aosedge/aos_common/blob/main/aoserrors/aoserrors.go"
    click AT "https://github.com/aosedge/aos_common/blob/main/aostypes/aostypes.go"
    click CP "https://github.com/aosedge/aos_common/tree/main/api/cloudprotocol/"
    click CM "https://github.com/aosedge/aos_common/tree/main/api/communicationmanager/"
    click IM "https://github.com/aosedge/aos_common/tree/main/api/iamanager/"
    click SM "https://github.com/aosedge/aos_common/tree/main/api/servicemanager/"
    click UM "https://github.com/aosedge/aos_common/tree/main/api/updatemanager/"
    click VP "https://github.com/aosedge/aos_common/tree/main/api/visprotocol/"
    click GP "https://github.com/aosedge/aos_common/blob/main/api/common/common.pb.go"
    click IMG "https://github.com/aosedge/aos_common/blob/main/image/image.go"
    click JA "https://github.com/aosedge/aos_common/blob/main/journalalerts/journalalerts.go"
    click MIG "https://github.com/aosedge/aos_common/blob/main/migration/migration.go"
    click PM "https://github.com/aosedge/aos_common/blob/main/partition/partition.go"
    click RM "https://github.com/aosedge/aos_common/blob/main/resourcemonitor/resourcemonitor.go"
    click SA "https://github.com/aosedge/aos_common/blob/main/spaceallocator/spaceallocator.go"
    click TPM "https://github.com/aosedge/aos_common/blob/main/tpmkey/tpmkey.go"
    click IAMC "https://github.com/aosedge/aos_common/blob/main/iamclient/iamclient.go"
    click WSC "https://github.com/aosedge/aos_common/blob/main/wsclient/wsclient.go"
    click WSS "https://github.com/aosedge/aos_common/blob/main/wsserver/wsserver.go"
    click UT "https://github.com/aosedge/aos_common/tree/main/utils/"
    click GH "https://github.com/aosedge/aos_common/tree/main/.github/workflows/"
    click GL "https://github.com/aosedge/aos_common/blob/main/.gitlab-ci.yml"
    click CIS "https://github.com/aosedge/aos_common/tree/main/ci/"
```
