# sovereignedgeeu-cognit/device-runtime-py architecture

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

- Interactive diagram: https://gitdiagram.com/sovereignedgeeu-cognit/device-runtime-py
- Repository: https://github.com/sovereignedgeeu-cognit/device-runtime-py

## Overview

##### Project Type and Purpose
- This project is a Python SDK designed to enable devices to communicate with the COGNIT platform for task offloading. It provides a high-level abstraction where devices can offload tasks via its built-in state machine.
- The README highlights two key components: the Cognit Frontend Client (for task offloading requests) and the Edge Cluster Frontend (for executing previously offloaded functions).

##### File Structure
- Top-Level Files: Look at files like LICENSE, README.md, setup.py, and requirements.txt which indicate a standard Python distribution.
- Package Structure: The main package ("cognit") includes submodules for device runtime and models and modules for different clients:
- The "cognit/device_runtime.py" file likely contains the core logic for the state machine managing communication.
- The "cognit/models" and "cognit/modules" directories contain distinct implementations for the Cognit Frontend Client, Edge Cluster Frontend Client, state machine, configuration, logger, and faas_parser.
- Tests and Examples: The separate test folders (with integration and unit tests) provide insight into how the components interact, and the examples directory shows minimal setups and configuration files.
- Documentation: The docs folder, including the state machine docs (device_runtime_sm.md), gives additional insights into how the state machine is designed.

##### Main Components
- Device Runtime Core:
- This is the central component that encapsulates the state machine (see files like _device_runtime_state_machine.py). It autonomously manages communication states.
- Cognit Frontend Client:
- Found in both the models and modules directories. This client handles task offloading setup requests and maintains policies/dependencies.
- Edge Cluster Frontend Client:
- Also present in both the models and modules directories. This component is responsible for executing offloaded tasks.
- Configuration & Environment:
- The configuration files (e.g., cognit.yml in the test/config directory and example configs) represent how the environment is set up.
- Testing & Examples:

##### Relationships and Interactions
- The Cognit Frontend Client: For sending function-offloading requests along with requirements, policies, etc.
- The Edge Cluster Frontend Client: For receiving and executing functions offloaded from the device.
- That the state machine in Device Runtime autonomously transitions between various states (e.g., idle, offloading, executing, error handling) and controls which external client (frontend or edge) is engaged at a given moment.

##### Architectural Patterns and Technologies
- Architectural Pattern: State Machine Pattern—central to the Device Runtime, ensuring that the communication flows and state transitions are managed automatically.
- Modular Design: Clear separation between models (data representations for clients) and modules (actual logic/operations for clients) emphasizes a separation of concerns.
- Python-based Implementation: Based on Python 3.10.6 as specified, with virtual environment setups and package distribution through setup.py.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Components
    subgraph "Internal Components"
        %% Device Runtime Core
        subgraph "Device Runtime Core"
            dr1["Core Device Runtime Logic"]:::core
            dr2["State Machine Implementation"]:::core
        end
        
        %% Clients
        subgraph "Clients"
            subgraph "Cognit Frontend Client"
                cfc1["Model Representation"]:::client
                cfc2["Module Implementation"]:::client
            end
            subgraph "Edge Cluster Frontend Client"
                ecc1["Model Representation"]:::client
                ecc2["Module Implementation"]:::client
            end
        end
        
        %% Configuration & Environment
        subgraph "Configuration & Environment"
            conf1["Test Configuration Files"]:::config
            conf2["Example Configuration"]:::config
        end
        
        %% Supporting Components
        subgraph "Supporting Components"
            test1["Unit Tests"]:::test
            test2["Integration Tests"]:::test
            ex1["Examples"]:::test
        end
    end

    %% External Systems
    subgraph "External Systems"
        ext["COGNIT Platform"]:::external
    end

    %% Relationships
    %% Device Runtime Core interactions with Clients and Configuration
    dr2 -->|"offload_request"| cfc1
    dr1 -->|"reads_config"| conf1

    %% Clients intercommunication for task execution
    cfc2 -->|"initiate_execution"| ecc1
    ecc2 -->|"result_feedback"| dr2

    %% Clients communication with External Systems
    cfc2 -->|"communicates_with"| ext
    ecc1 -->|"communicates_with"| ext

    %% Configuration influencing Client operations
    conf1 -->|"provides_settings"| cfc2
    conf1 -->|"provides_settings"| ecc2

    %% Supporting components validating interactions (dashed arrows)
    test1 -.-> dr1
    test1 -.-> cfc1
    test2 -.-> dr2
    ex1 -.-> conf2

    %% Click Events
    click dr1 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/blob/main/cognit/device_runtime.py"
    click dr2 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/blob/main/cognit/modules/_device_runtime_state_machine.py"
    click cfc1 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/blob/main/cognit/models/_cognit_frontend_client.py"
    click cfc2 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/blob/main/cognit/modules/_cognit_frontend_client.py"
    click ecc1 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/blob/main/cognit/models/_edge_cluster_frontend_client.py"
    click ecc2 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/blob/main/cognit/modules/_edge_cluster_frontend_client.py"
    click conf1 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/tree/main/cognit/test/config"
    click conf2 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/blob/main/examples/cognit-template.yml"
    click test1 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/tree/main/cognit/test/unit"
    click test2 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/tree/main/cognit/test/integration"
    click ex1 "https://github.com/sovereignedgeeu-cognit/device-runtime-py/blob/main/examples/minimal_offload_sync.py"

    %% Styles
    classDef core fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef client fill:#99CCFF,stroke:#333,stroke-width:2px;
    classDef config fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef test fill:#FF9999,stroke:#333,stroke-width:2px;
    classDef external fill:#D0B0FF,stroke:#333,stroke-width:2px;
```
