# fiatrete/opendan-personal-ai-os architecture

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

- Interactive diagram: https://gitdiagram.com/fiatrete/opendan-personal-ai-os
- Repository: https://github.com/fiatrete/opendan-personal-ai-os

## Overview

##### Project Type and Purpose
- The project is a full-fledged personal AI OS that consolidates various AI modules and agents into one cohesive system. It is designed to enable users to deploy, switch, and manage diverse AI agents (e.g., Jarvis, Mia, Tracy, etc.) along with workflows, knowledge bases, and external integrations (such as Telegram, email, and IoT devices).
- It emphasizes modularity, extensibility, and containerized deployment (via Docker), with components for AI processing, service orchestration, package management, and even UI elements for a shell-like experience.

##### Analyzing the File Structure
- Several top-level directories indicate key architectural components:
- PoC: Contains proof-of-concept modules (e.g., agent_jarvis, discord_bot) that show early versions of operational agents.
- src: Houses the core “aios” framework, including agents, environment modules, network layers, package manager, proto definitions, data storage, and utilities.
- rootfs: Defines runtime configurations for agents and workflows that mirror the “operating system” layout, including agent configurations (agent.toml files) and workflow settings.
- test: Contains unit and integration tests, reflecting component boundaries.
- component: Includes modules that tie agents with external platforms (Discord, email, Google services, etc.) and manage specialized nodes (OpenAI, LLaMa, SD nodes, etc.).
- There are multiple configuration and build files (Dockerfile, .env_templates, supervisor configurations) which delineate containerization and runtime orchestration.

##### Main Components
a. AIOS Kernel and Core Framework (src/aios)
- Core agent framework, memory management, language model interface, and compute nodes.
- Modules (agent, llm_process, package_manager, knowledge handlers, storage, etc.).
b. AI Agents and Agent Manager (rootfs/agents and component/agent_manager)
- How the agent manager orchestrates these individual agents.
c. Workflow Manager
- Components from the workflow_manager module and examples like the “story_maker” workflow.
d. External Interfaces and Tunnels
- Integration with external services through Discord (discord_bot), Telegram and email tunnels, file systems, IoT devices, etc.
e. Package Management and Module Extensibility (src/aios/package_manager and example_modules)
- How new agents/modules are added to the system or updated and how their packages are managed.
f. Containerization / Deployment Infrastructure
- Docker as the container for the application, including build and run scripts (e.g., Dockerfiles, build_docker.sh, supervisor configurations).

##### Relationships and Interactions
- How the core AIOS kernel communicates with individual AI agents, using service APIs, message passing (e.g., via proto messages) and workflow orchestration.
- How external communication channels (Docker, network endpoints) interact with agents and workflows.
- Data flow between the local knowledge base (which aggregates and indexes personal data) and AI agents that perform tasks.
- Dependency relations between core modules—for example, the package manager delivering agent/module updates, and the agent manager coordinating activities.

##### Architectural Patterns and Design Principles
- Microservices / Modular Design: Each agent or component (even if hosted inside the same container) is conceptually a separate “service” functioning together.
- Containerization / Deployment Architecture: Docker-based deployment ensures that the runtime remains consistent across various hardware (PC, Mac, RaspberryPI, etc.).
- Plugin Architecture: The system is built for extensibility, as seen in “example_modules” and package manager modules.
- Event-Driven / Message-based Communication: The design involves a messaging interface (evident from the proto files and chat sessions) that enables agents to communicate.

- A block for the Docker/Container layer with the deployed OpenDAN image.
- A separate block for the AIOS Core/Kernal, encapsulating agent management, protocol handling (proto), storage, and compute nodes.
- A block for the Workflow Manager coordinating multi-agent workflows.
- Integration blocks for external tunnels and interfaces (Discord Bot, email, IoT control).
- An area for the Package Manager and Module Loader that handles extensibility and configuration (referencing the package_manager and example_modules directories).
- An optional block for the test infrastructure, if needed to show continuous integration or test flows.

– Every major component of OpenDAN
– Their interactions (data flow, control commands, service dependencies)
– Key architectural patterns (modularity, containerization, service orchestration, extensibility)
– The mix of traditional OS concepts with modern AI agent integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        D1["Dockerfile"]:::deployment
        D2["Jarvis Build Script"]:::deployment
        D3["Supervisor Configs"]:::deployment
    end

    %% Core Services
    subgraph "Core Services"
        C["AIOS Core/Kernel"]:::core
    end

    %% Module Management
    subgraph "Module Management"
        subgraph "Package Management & Extensibility"
            PM["Package Manager"]:::package
            EM["Example Modules"]:::package
        end
    end

    %% AI Agents & Agent Manager
    subgraph "AI Agents & Agent Manager"
        A1["Agent Configs"]:::agent
        A2["Agent Manager Service"]:::agent
    end

    %% Workflow Manager
    subgraph "Workflow Manager"
        W1["Workflow Configs"]:::workflow
        W2["Workflow Service"]:::workflow
    end

    %% External Interfaces & Tunnels
    subgraph "External Interfaces & Tunnels"
        E1["Discord Tunnel"]:::external
        E2["Email Tunnel"]:::external
        E3["Slack Tunnel"]:::external
        E4["Telegram Tunnel"]:::external
    end

    %% Connections
    D1 -->|"deploys"| C
    D2 --> C
    D3 --> C

    C -->|"manages"| A1
    C -->|"controls"| A2
    C -->|"provides"| PM
    C -->|"supplies"| EM

    A1 -->|"triggers"| W1
    A2 -->|"initiates"| W2

    PM -->|"updates"| A2
    EM -->|"extends"| A2

    W1 -->|"interfaces"| E1
    W1 -->|"interfaces"| E2
    W2 -->|"interfaces"| E3
    W2 -->|"interfaces"| E4

    %% Click Events
    click D1 "https://github.com/fiatrete/opendan-personal-ai-os/tree/main/Dockerfile"
    click D2 "https://github.com/fiatrete/opendan-personal-ai-os/blob/main/PoC/agent_jarvis/build_docker.sh"
    click D3 "https://github.com/fiatrete/opendan-personal-ai-os/blob/main/PoC/agent_jarvis/supervisor.d"
    click C "https://github.com/fiatrete/opendan-personal-ai-os/tree/main/src/aios"
    click A1 "https://github.com/fiatrete/opendan-personal-ai-os/tree/main/rootfs/agents"
    click A2 "https://github.com/fiatrete/opendan-personal-ai-os/blob/main/src/component/agent_manager/agent_manager.py"
    click W1 "https://github.com/fiatrete/opendan-personal-ai-os/tree/main/rootfs/workflows"
    click W2 "https://github.com/fiatrete/opendan-personal-ai-os/blob/main/src/component/workflow_manager/workflow_manager.py"
    click PM "https://github.com/fiatrete/opendan-personal-ai-os/tree/main/src/aios/package_manager"
    click EM "https://github.com/fiatrete/opendan-personal-ai-os/tree/main/PoC/example_modules"
    click E1 "https://github.com/fiatrete/opendan-personal-ai-os/blob/main/src/component/discord_tunnel.py"
    click E2 "https://github.com/fiatrete/opendan-personal-ai-os/blob/main/src/component/email_tunnel.py"
    click E3 "https://github.com/fiatrete/opendan-personal-ai-os/blob/main/src/component/slack_tunnel.py"
    click E4 "https://github.com/fiatrete/opendan-personal-ai-os/blob/main/src/component/tg_tunnel.py"

    %% Styles
    classDef deployment fill:#FFD54F,stroke:#F57F17,stroke-width:2px;
    classDef core fill:#AED581,stroke:#33691E,stroke-width:2px;
    classDef package fill:#CE93D8,stroke:#6A1B9A,stroke-width:2px;
    classDef agent fill:#81D4FA,stroke:#01579B,stroke-width:2px;
    classDef workflow fill:#FFCC80,stroke:#FB8C00,stroke-width:2px;
    classDef external fill:#FFAB91,stroke:#D84315,stroke-width:2px;
```
