# openatom-linyaps/linyaps architecture

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

- Interactive diagram: https://gitdiagram.com/openatom-linyaps/linyaps
- Repository: https://github.com/openatom-linyaps/linyaps

## Overview

##### Project Type and Purpose
- Linglong is clearly a container management and runtime toolkit – its “container” metaphor (tower layers, container control) is central. The purpose is to offer a full suite of libraries and applications that manage containerized applications, including building and launching containers.
- The multiple “apps” directories provide distinct front-end tools (CLI, GUI dialog, session helper, package manager, etc.) that interact with back-end libraries.
- The libraries (e.g., libs/linglong, libs/api, libs/dbus-api, libs/ocppi, libs/oci-cfg-generators, libs/utils) implement the core functionality: container API types, DBus communications, container runtime interactions, and configuration generation.

##### Analysis of the File Structure
- Top-Level Structure:
- Build and configuration files (CMakeLists.txt, CMakePresets.json, etc.) signal a CMake-based C++ system.
- The “libs” directory is divided into several parts:
∘ libs/api: Contains API type definitions and JSON/YAML schema for container management.
∘ libs/dbus-api: Contains DBus interface implementations to offer IPC.
∘ libs/linglong: Core container management logic – builder, package, runtime, repository, and client factory.
∘ libs/oci-cfg-generators: Tools for generating OCI configuration files.
∘ libs/ocppi: Provides a C++ interface to container runtime operations (wrappers around common container operations).
∘ libs/utils: Contains utility functions like error handling, file IO, serialization, and helper functions.
- The “misc” and “tools” directories include supplementary scripts, code generators, and helper binaries for building, coverage, and testing.
- An “external” directory containing third-party libraries (like CLI11, tl-expected, http) indicates reliance on external tooling for command-line parsing, error handling, and API clients.
- The “api” directory includes DBus and HTTP API definitions (XML and Swagger JSON/YAML) that provide a formal contract for communicating with container management routines.

##### Main Components
- User-Facing Applications:
- ll-cli (command-line interface)
- ll-dialog (graphical pop-up or permission dialog)
- ll-builder (for building container images/configurations)
- ll-package-manager, ll-session-helper and others – each offering a dedicated utility.
- Core Libraries:
- API Layer (libs/api): Defines data types and schemas for container operations.
- DBus API (libs/dbus-api): Handles inter-process communications, permitting remote control of container operations.
- Central Container Manager (libs/linglong): Implements core container lifecycle management (container building, package handling, launching, and runtime management).
- OCI Config Generators (libs/oci-cfg-generators): Provides generation of container config files – essential for an OCI-compliant runtime.
- Container Runtime Interface (libs/ocppi): Wraps interactions with container runtimes (interfaces to crun, runc, youki, etc.) and provides error handling and process control.
- Utilities (libs/utils): Encapsulates common tasks like error propagation, file management, serialization (JSON/YAML), and configuration helpers.
- Supporting Components:
- External Libraries (CLI11, tl-expected, and HTTP libraries) which are used across different components.
- DBus and HTTP APIs, as defined under “api”, that connect these libraries with clients either locally or over the network.
- Tools and Scripts (from the “tools” and “misc” directories) which automate tasks such as code generation, testing, building coverage, and system integration.

##### Relationships and Interactions
- The API layer (libs/api) ensures that all data exchanges follow a consistent contract, both for DBus and HTTP interfaces.
- The DBus API (libs/dbus-api) abstracts system-level communication, letting components in different processes or on different layers exchange messages reliably.
- The container runtime components (libs/linglong and libs/ocppi) implement the logic for container lifecycle events (creation, monitoring, teardown) and generate or validate OCI configuration through libs/oci-cfg-generators.
- Utility libraries provide shared services across the system.
- External libraries (from the “external” dir) are integrated into many components for tasks like command-line parsing or error handling.

##### Final Advice
- Keep it granular enough to capture every major module (even if it means several sub-components) so that the design effectively communicates each layer of abstraction.
- As Linglong uses both DBus and HTTP-based APIs (evident from the “api” directory), make sure to represent these communication channels and emphasize the layered “tower” architecture that inspired the project’s name.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-Facing Applications
    subgraph "User-Facing Applications"
        CLI["ll-cli"]:::user
        DIALOG["ll-dialog"]:::user
        BUILDER["ll-builder"]:::user
        PACKAGE["ll-package-manager"]:::user
        SESSION["ll-session-helper"]:::user
        BOX["ll-box"]:::user
    end

    %% Core Libraries
    subgraph "Core Libraries"
        API["API Layer"]:::core
        DBUS["DBus API"]:::core
        CMC["Central Container Manager"]:::core
        OCI["OCI Config Generators"]:::core
        CRI["Container Runtime Interface"]:::core
        UTILS["Utilities"]:::core
    end

    %% Supporting Components
    subgraph "Supporting Components"
        API_DEF["API Definitions"]:::support
        EX_CLI11["CLI11"]:::support
        EX_TLE["tl-expected"]:::support
        EX_HTTP["HTTP Libraries"]:::support
        TOOLS["Tools and Automation Scripts"]:::support
    end

    %% Relationships: User-Facing Applications to Core Libraries
    CLI -->|"sendsCommands"| DBUS
    DIALOG -->|"dialogRequest"| DBUS
    BUILDER -->|"initBuild"| CMC
    PACKAGE -->|"managePackages"| CMC
    SESSION -->|"sessionMgmt"| CMC
    BOX -->|"overview"| CMC

    %% Relationships within Core Libraries
    DBUS -->|"relaysControl"| CMC
    API -->|"definesSchemas"| DBUS
    CMC -->|"triggersOCI"| OCI
    OCI -->|"generatesOCI"| CRI
    UTILS -->|"supports"| CMC

    %% Relationships: Supporting Components with Core and APIs
    API_DEF -->|"contracts"| API
    EX_CLI11 -->|"cliParsing"| CLI
    EX_TLE -->|"errorHandling"| CMC
    EX_HTTP -->|"httpCalls"| API_DEF
    TOOLS -->|"buildAutomation"| CMC

    %% Styles
    classDef user fill:#BBDEFB,stroke:#0d47a1,stroke-width:2px
    classDef core fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px
    classDef support fill:#FFECB3,stroke:#FF6F00,stroke-width:2px

    %% Click Events for User-Facing Applications
    click CLI "https://github.com/openatom-linyaps/linyaps/tree/master/apps/ll-cli"
    click DIALOG "https://github.com/openatom-linyaps/linyaps/tree/master/apps/ll-dialog"
    click BUILDER "https://github.com/openatom-linyaps/linyaps/tree/master/apps/ll-builder"
    click PACKAGE "https://github.com/openatom-linyaps/linyaps/tree/master/apps/ll-package-manager"
    click SESSION "https://github.com/openatom-linyaps/linyaps/tree/master/apps/ll-session-helper"
    click BOX "https://github.com/openatom-linyaps/linyaps/tree/master/apps/ll-box"

    %% Click Events for Core Libraries
    click API "https://github.com/openatom-linyaps/linyaps/tree/master/libs/api"
    click DBUS "https://github.com/openatom-linyaps/linyaps/tree/master/libs/dbus-api"
    click CMC "https://github.com/openatom-linyaps/linyaps/tree/master/libs/linglong"
    click OCI "https://github.com/openatom-linyaps/linyaps/tree/master/libs/oci-cfg-generators"
    click CRI "https://github.com/openatom-linyaps/linyaps/tree/master/libs/ocppi"
    click UTILS "https://github.com/openatom-linyaps/linyaps/tree/master/libs/utils"

    %% Click Events for Supporting Components
    click API_DEF "https://github.com/openatom-linyaps/linyaps/tree/master/api"
    click EX_CLI11 "https://github.com/openatom-linyaps/linyaps/tree/master/external/CLI11"
    click EX_TLE "https://github.com/openatom-linyaps/linyaps/tree/master/external/tl-expected"
    click EX_HTTP "https://github.com/openatom-linyaps/linyaps/tree/master/external/http"
    click TOOLS "https://github.com/openatom-linyaps/linyaps/tree/master/tools"
```
