# agenttankos/tankwork architecture

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

- Interactive diagram: https://gitdiagram.com/agenttankos/tankwork
- Repository: https://github.com/agenttankos/tankwork

## Overview

##### Project Type & Purpose
- TankWork is a desktop agent framework aimed at developers and researchers experimenting with autonomous computer control. It offers two distinct modes – “Computer Use Mode” for direct system control and “Assistant Mode” for screen analysis with skills like ticker analysis.
- The project integrates components for computer vision, voice processing, command handling, and agent configuration, all orchestrated by a central entry point (main.py).

##### File Structure
- Core Functionality (core directory):
- Avatar Subsystem: Contains avatar event handling, manager, and models used for configuring and working with agent visual/voice representations.
- Command Handling: The command accelerator, command manager, and dedicated modules (e.g., core/command_accelerator, core/command_manager) indicate a subsystem for interpreting and routing commands.
- Computer Use & Interface: Modules such as computer_use_factory, computer_use_interface, and computer_use_providers (e.g., the tank implementation in computer_use_providers) suggest pluggable implementations for direct computer control.
- Narrative Processing: The narrative_processor.py module sets up real-time text feedback and analysis.
- Example Skill: The ticker analysis under core/skills demonstrates one of possibly many skills that process screen content.
- Voice Integration: Modules for voice and voice_commands integrate voice recognition and natural language processing.
- Screenshot Functionality: Provides screen capture capabilities to enable vision analysis.
- UI Layer (ui directory):
- Contains user interface components like app.py, loading_eyes.py, and notification.py. This layer likely handles feedback, visualization, and user interaction.
- Configuration & Assets:
- The config directory holds key configuration files for avatars, general settings, and logging.
- Assets (including avatars, images, and videos) provide the necessary multimedia components for the visual identity of each agent.

##### Main Components & Their Interactions
- Main Entry Point (main.py): Acts as the bootstrapper that initializes configurations, core functionalities, and the UI.
- Core Modules:
- Avatar Management: Handles agent configuration and interaction with customizable avatars.
- Command Processing: Receives and interprets both voice and text commands. It further routes these commands to the appropriate submodules (e.g., computer use providers or skill processors).
- Computer Use Providers: Implements the logic for direct computer control (using various providers, with “tank” as one default).
- Narrative & Feedback: Processes screen captures and logs audio-visual feedback, ready to be presented by the UI.
- Voice System: Integrates with ElevenLabs and other APIs to enable natural language voice command services.
- UI Components: Visual interface modules that present information (action logs, notifications, visual cues like “loading eyes”) and accept user input.

##### Architectural Patterns & Principles
- Modular Design: The project’s structure is clearly divided into independent modules (e.g., core, ui, config, assets). Highlighting this separation ensures clarity regarding which modules manage particular responsibilities.
- Plugin/Provider Pattern: The computer use providers (and, by extension, custom skills) suggest a pluggable system where different “implementation” modules can be swapped or extended.
- Configurable Agents: The extensive agent configuration system indicates a design that values extensibility and customizability.
- Separation of Concerns: Interaction (voice and textual) and computational tasks (command processing, vision analysis, computer control) are encapsulated in different layers.

##### Final Checklist for the Principal Software Engineer
- Core: Avatar (with events, manager, models), Command Accelerator & Manager, Computer Use (factory, interface, providers), Narrative Processor, Screenshot, Skills (Ticker Analysis), Voice & Commands.
- UI: App, Loading Eyes, Notification.
- Config: Configuration modules (general config, avatar config, logging config).
- Assets: Avatars (images, videos, etc.).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Main Entry Point
    main["main.py"]:::main

    %% Configurations
    subgraph "Configurations"
        configAvatar["Avatar_config"]:::config
        configGeneral["General_Config"]:::config
        configLogging["Logging_Config"]:::config
    end

    %% Assets
    subgraph "Assets"
        assetsMedia["Multimedia Assets"]:::assets
    end

    %% External APIs/Services
    subgraph "External_APIs"
        elevenLabs["ElevenLabs"]:::external
        openAI["OpenAI"]:::external
        gemini["Gemini"]:::external
        anthropic["Anthropic"]:::external
    end

    %% Core Modules
    subgraph "Core_Modules"
        %% Avatar Management
        subgraph "Avatar Management"
            avatarEvents["Avatar Events"]:::core
            avatarManager["Avatar Manager"]:::core
            avatarModels["Avatar Models"]:::core
        end

        %% Command Processing
        subgraph "Command Processing"
            cmdAccelerator["General_Command_Accelerator"]:::core
            commandManager["Command Manager"]:::core
        end

        %% Computer Use Providers
        subgraph "Computer Use Providers"
            computerUseFactory["Computer_Use_Factory"]:::core
            computerUseInterface["Computer_Use_Interface"]:::core
            computerProviderTank["Provider_Tank"]:::core
            computerUseTankRef["Computer_Use_Tank_Ref"]:::core
        end

        %% Narrative Processing
        narrativeProcessor["Narrative Processor"]:::core

        %% Screenshot Functionality
        screenshotFunction["Screenshot Functionality"]:::core

        %% Skill (Ticker Analysis)
        subgraph "Skill_Ticker_Analysis"
            skillTickerAnalysis["Ticker Analysis"]:::core
        end

        %% Voice Integration
        subgraph "Voice Integration"
            voiceSystem["Voice System"]:::core
            voiceCommands["Voice Commands"]:::core
        end
    end

    %% UI Components
    subgraph "UI_Layer"
        uiApp["App"]:::ui
        uiLoading["Loading Eyes"]:::ui
        uiNotification["Notification"]:::ui
    end

    %%--------------- Connections ---------------

    %% Main initialization flows
    main -->|"init_config"| configGeneral
    main -->|"init_config"| configAvatar
    main -->|"init_config"| configLogging
    main -->|"init"| assetsMedia
    main -->|"start"| commandManager
    main -->|"start"| uiApp

    %% UI sends commands to Command Manager
    uiApp -->|"send_command"| commandManager
    uiNotification -->|"display_feedback"| commandManager

    %% Command Manager dispatches to various core modules
    commandManager -->|"accelerate"| cmdAccelerator
    commandManager -->|"for_control"| computerUseFactory
    commandManager -->|"for_control"| computerUseInterface
    commandManager -->|"for_assistant"| narrativeProcessor
    commandManager -->|"for_assistant"| screenshotFunction
    commandManager -->|"for_skill"| skillTickerAnalysis
    commandManager -->|"for_voice"| voiceSystem

    %% Voice Integration interactions with External APIs
    voiceSystem -->|"synthesize"| elevenLabs
    voiceSystem -->|"process"| openAI
    voiceCommands -->|"process"| gemini
    voiceCommands -->|"process"| anthropic

    %% Core internal interactions
    computerUseFactory -->|"uses"| computerUseTankRef
    computerUseInterface -->|"routes_to"| computerProviderTank
    voiceSystem -->|"triggers"| voiceCommands

    %% Feedback from core modules to UI
    narrativeProcessor -->|"feedback"| uiNotification
    screenshotFunction -->|"capture"| uiNotification
    skillTickerAnalysis -->|"result"| uiNotification

    %%--------------- Click Events ---------------
    click main "https://github.com/agenttankos/tankwork/blob/main/main.py"
    click avatarEvents "https://github.com/agenttankos/tankwork/blob/main/core/avatar/events.py"
    click avatarManager "https://github.com/agenttankos/tankwork/blob/main/core/avatar/manager.py"
    click avatarModels "https://github.com/agenttankos/tankwork/blob/main/core/avatar/models.py"
    click cmdAccelerator "https://github.com/agenttankos/tankwork/blob/main/core/command_accelerator/general_command_accelerator.py"
    click commandManager "https://github.com/agenttankos/tankwork/blob/main/core/command_manager.py"
    click computerUseFactory "https://github.com/agenttankos/tankwork/blob/main/core/computer_use_factory.py"
    click computerUseInterface "https://github.com/agenttankos/tankwork/blob/main/core/computer_use_interface.py"
    click computerProviderTank "https://github.com/agenttankos/tankwork/tree/main/core/computer_use_providers/computer_use_tank"
    click computerUseTankRef "https://github.com/agenttankos/tankwork/blob/main/core/computer_use_tank.py"
    click narrativeProcessor "https://github.com/agenttankos/tankwork/blob/main/core/narrative_processor.py"
    click screenshotFunction "https://github.com/agenttankos/tankwork/blob/main/core/screenshot.py"
    click skillTickerAnalysis "https://github.com/agenttankos/tankwork/tree/main/core/skills/ticker_analysis"
    click voiceSystem "https://github.com/agenttankos/tankwork/blob/main/core/voice.py"
    click voiceCommands "https://github.com/agenttankos/tankwork/blob/main/core/voice_commands.py"
    click uiApp "https://github.com/agenttankos/tankwork/blob/main/ui/app.py"
    click uiLoading "https://github.com/agenttankos/tankwork/blob/main/ui/loading_eyes.py"
    click uiNotification "https://github.com/agenttankos/tankwork/blob/main/ui/notification.py"
    click configAvatar "https://github.com/agenttankos/tankwork/blob/main/config/avatar_config.py"
    click configGeneral "https://github.com/agenttankos/tankwork/blob/main/config/config.py"
    click configLogging "https://github.com/agenttankos/tankwork/blob/main/config/logging_config.py"
    click assetsMedia "https://github.com/agenttankos/tankwork/tree/main/assets/avatars"

    %%--------------- Styles ---------------
    classDef main fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef core fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef ui fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef config fill:#d6eaf8,stroke:#2980b9,stroke-width:2px;
    classDef assets fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#e74c3c,stroke-width:2px;
```
