# daveshap/ace_framework architecture

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

- Interactive diagram: https://gitdiagram.com/daveshap/ace_framework
- Repository: https://github.com/daveshap/ace_framework

## Overview

##### Main Components
- Core Engine and Framework:
- Components like the “ace” directory (in ACE_PRIME/HelloAF and CORE_DEMOS/hello-layers) include the core runtime, messaging, API endpoints, and layer management. This is the brain of the system.
- Specific modules such as the framework layer, telemetry (telemetry_environment and telemetry_user), resource management, and logging.
- Messaging & Communication Layer:
- Multiple AMQP-related files (e.g., connection.py, config_parser.py, setup.py) indicate a dedicated asynchronous messaging bus. Highlight how this facilitates internal communication between the layers and external triggers.
- Client and API Endpoints:
- There are files like api_endpoint.py, debug_endpoint.py, and REST/Flask or Rails components (e.g., in the iACEui and python-flask-react directories) that handle user or external service integrations.
- Demo Implementations and Frontends:
- The repo includes multiple demo projects (e.g., ACE_PRIME/HelloAF, CORE_DEMOS, iACEui, rails, python-flask-react, stacey) that illustrate variations or implementations of the ACE framework.
- These projects may incorporate Docker/Docker Compose deployments; include these deployment artifacts to show containerized components.
- External Interfaces and Infrastructure:
- Dockerfiles, docker-compose files, and various configuration files indicate container orchestration. These are part of the deployment layer.
- Communication channels for different contexts (discord, web, etc.) are also evident in directories under CORE_DEMOS/stacey/backend and similar.

##### Out Key Relationships and Data Flows
- Framework Core (layer management, resource and telemetry management, and LLM integrations)
- Messaging Bus (AMQP setup and connections)
- Debug and API endpoints.
- Link to adjacent blocks representing “Client Interfaces” / “Frontends”:
- Where appropriate, show separate channels for asynchronous messaging (AMQP) that interact with both the core and external tools (bots, web channels).

##### Architectural Patterns & Design Principles
- Use of a layered or modular architecture:
- The multi-layer approach (e.g., different “layers” like layer_1 (aspirational), layer_2 (strategy), etc., seen both in ACE_PRIME and CORE_DEMOS) will be depicted as sequential or interconnected modules.
- Tenant of “Avoiding Overcomplication” – keep components decoupled so that revisions or new implementations can be integrated.
- “Task-Constrained Approach” by showing how specific actions (for example, agent actions in the AMQP messaging or API endpoint calls) trigger cascaded processes through defined modules.

##### Including Relevant Technologies & Frameworks
- That Python is the primary language for the core engine.
- Docker and Docker Compose for containerization.
- Integration points for messaging systems (AMQP modules).
- Use of frontend technologies (Svelte components in iACEui, React/Next.js in python-flask-react, Kivy for certain UIs) and Rails for another interface.
- Call out telemetry components and resource managers as distinct, supporting modules.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Core ACE Engine"
        ACE_Core["ACE Framework Core"]:::core
        AMQP["AMQP Messaging"]:::comm
        API["API & Debug Endpoints"]:::api
        Telemetry["Telemetry & Resource Management"]:::telemetry
        ACE_Core -->|"manages"| Telemetry
        ACE_Core -->|"exposes"| API
        ACE_Core -->|"interfaces"| AMQP
    end

    subgraph "Client Interfaces & Demo Projects"
        UI["Generic UI/Client"]:::frontend
        Demo1["HelloAF Demo"]:::demo
        Demo2["AceAF Demo"]:::demo
        Demo3["Hello-Layers Demo"]:::demo
        Demo4["iACEui (Svelte)"]:::demo
        Demo5["Python Frontend (Flask/React)"]:::demo
        Demo6["Stacey Demo"]:::demo
    end

    subgraph "Deployment & Containerization"
        Deployment["Docker & Orchestration"]:::deploy
    end

    %% Connections between core and demos/UI
    UI -->|"callsAPI"| API
    Demo1 -->|"integrates"| ACE_Core
    Demo2 -->|"integrates"| ACE_Core
    Demo3 -->|"integrates"| ACE_Core
    Demo4 -->|"callsAPI"| API
    Demo5 -->|"callsAPI"| API
    Demo6 -->|"callsAPI"| API

    %% Internal core communication
    API -->|"sendsTelemetry"| Telemetry
    AMQP -->|"communicates"| ACE_Core

    %% Deployment connections
    Deployment -->|"deploys"| ACE_Core
    Deployment -->|"deploys"| Demo1
    Deployment -->|"deploys"| Demo2
    Deployment -->|"deploys"| Demo3
    Deployment -->|"deploys"| Demo4
    Deployment -->|"deploys"| Demo5
    Deployment -->|"deploys"| Demo6
    Deployment -->|"deploys"| UI

    %% Click Events for Core Engine and Framework
    click ACE_Core "https://github.com/daveshap/ace_framework/tree/main/ACE_PRIME/HelloAF/src/ace/"
    click ACE_Core "https://github.com/daveshap/ace_framework/tree/main/ACE_PRIME/HelloAF/src/ace/framework/"
    click ACE_Core "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/hello-layers/src/ace/framework/"

    %% Click Events for Messaging & Communication Layer
    click AMQP "https://github.com/daveshap/ace_framework/tree/main/ACE_PRIME/HelloAF/src/ace/amqp/"
    click AMQP "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/hello-layers/src/ace/amqp/"

    %% Click Events for Client and API Endpoints
    click API "https://github.com/daveshap/ace_framework/blob/main/ACE_PRIME/HelloAF/src/ace/api_endpoint.py"
    click API "https://github.com/daveshap/ace_framework/blob/main/ACE_PRIME/HelloAF/src/ace/debug_endpoint.py"
    click API "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/iACEui/src/ace/app/api/"
    click API "https://github.com/daveshap/ace_framework/blob/main/CORE_DEMOS/rails/app/controllers/messages_controller.rb"

    %% Click Events for Demo Implementations and Frontends
    click Demo1 "https://github.com/daveshap/ace_framework/tree/main/ACE_PRIME/HelloAF"
    click Demo2 "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/AceAF"
    click Demo3 "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/hello-layers"
    click Demo4 "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/iACEui"
    click Demo5 "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/python-flask-ez"
    click Demo5 "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/python-flask-react"
    click Demo6 "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/stacey"

    %% Click Events for Deployment Artifacts
    click Deployment "https://github.com/daveshap/ace_framework/tree/main/ACE_PRIME/HelloAF"
    click Deployment "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/hello-layers"
    click Deployment "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/iACEui"
    click Deployment "https://github.com/daveshap/ace_framework/tree/main/CORE_DEMOS/python-flask-react"
    click Deployment "https://github.com/daveshap/ace_framework/blob/main/CORE_DEMOS/stacey/backend/config/examples/docker-compose.yml"

    %% Click Events for Telemetry and Resource Management
    click Telemetry "https://github.com/daveshap/ace_framework/tree/main/ACE_PRIME/HelloAF/src/ace/framework/telemetry/"
    click Telemetry "https://github.com/daveshap/ace_framework/blob/main/ACE_PRIME/HelloAF/resource_manager.py"
    click Telemetry "https://github.com/daveshap/ace_framework/blob/main/ACE_PRIME/HelloAF/src/ace/framework/resource.py"
    click Telemetry "https://github.com/daveshap/ace_framework/tree/main/ACE_PRIME/HelloAF/src/ace/framework/resources/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef comm fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef telemetry fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef frontend fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef demo fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef deploy fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
