# bencbartlett/overmind architecture

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

- Interactive diagram: https://gitdiagram.com/bencbartlett/overmind
- Repository: https://github.com/bencbartlett/overmind

## Overview

##### Main Components

a. Core Control Layer:
- Colony (manages individual room operations)
- Overseer (coordinates colony-level decisions)
- Assimilator (enables multi-player hivemind functionality)

b. Operational Layers:
- Directives System (strategic decision-making)
- Overlords System (tactical unit control)
- Logistics Network (resource management)
- Combat Systems (military operations)

c. Support Systems:
- Memory Management
- Caching System
- Console/Debugging
- Statistics/Metrics

##### Component Relationships

a. Control Flow:
- Overseer → Colonies → Overlords → Creeps
- Directives → HiveClusters → Tasks
- Assimilator ←→ Other Players' Overmind Instances

b. Resource Management:
- LogisticsNetwork → {TerminalNetwork, LinkNetwork, SpawnGroup}
- Energetics → Resource Distribution
- TradeNetwork → Inter-Colony Resource Exchange

##### Specific Implementation Details

Specialized subsystems:
- Room Planning System (BasePlanner, RoadPlanner, BarrierPlanner)
- Combat Intelligence (CombatIntel, RoomIntel)
- Movement System (Pathing, Movement helpers)
- Task Management System

##### Special Notes

- Hivemind nature of the system with the Assimilator
- How the system integrates with the game's API
- Stats collection system feeding into Grafana
- Autonomous decision-making pathways

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Core["Core Control Layer"]
        Overseer["Overseer"]:::core
        Colony["Colony"]:::core
        Assimilator["Assimilator"]:::core
    end

    subgraph Operations["Operational Layer"]
        Directives["Directives System"]:::ops
        Overlords["Overlords System"]:::ops
        LogisticsNet["Logistics Network"]:::ops
        Combat["Combat Systems"]:::ops
    end

    subgraph Support["Support Systems"]
        Memory[(Memory)]:::support
        Cache[(Cache)]:::support
        Console["Console/Debugging"]:::support
        Stats["Statistics"]:::support
    end

    subgraph Planning["Planning Systems"]
        RoomPlanner["Room Planning"]:::planning
        CombatIntel["Combat Intelligence"]:::planning
        Movement["Movement System"]:::planning
        TaskMgmt["Task Management"]:::planning
    end

    subgraph Logistics["Logistics Components"]
        Terminal["Terminal Network"]:::logistics
        Link["Link Network"]:::logistics
        Spawn["Spawn Group"]:::logistics
        Trade["Trade Network"]:::logistics
        HiveCluster["Hive Clusters"]:::logistics
    end

    %% Core relationships
    Overseer --> Colony
    Colony --> Overlords
    Assimilator <--> OtherPlayers["Other Players"]

    %% Operational flows
    Directives --> HiveCluster
    HiveCluster --> TaskMgmt
    Overlords --> Combat
    LogisticsNet --> Terminal
    LogisticsNet --> Link
    LogisticsNet --> Spawn
    LogisticsNet --> Trade

    %% Support system connections
    Memory --> Overseer
    Cache --> Colony
    Console --> Support
    Stats --> Support

    %% Planning system integrations
    RoomPlanner --> Colony
    CombatIntel --> Combat
    Movement --> Overlords
    TaskMgmt --> Overlords

    %% Click events
    click Overseer "https://github.com/bencbartlett/Overmind/blob/master/src/Overseer.ts"
    click Colony "https://github.com/bencbartlett/Overmind/blob/master/src/Colony.ts"
    click Assimilator "https://github.com/bencbartlett/Overmind/blob/master/src/assimilation/Assimilator_obfuscated.js"
    click Directives "https://github.com/bencbartlett/Overmind/blob/master/src/directives/Directive.ts"
    click Overlords "https://github.com/bencbartlett/Overmind/blob/master/src/overlords/Overlord.ts"
    click LogisticsNet "https://github.com/bencbartlett/Overmind/blob/master/src/logistics/LogisticsNetwork.ts"
    click Combat "https://github.com/bencbartlett/Overmind/blob/master/src/zerg/CombatZerg.ts"
    click Memory "https://github.com/bencbartlett/Overmind/blob/master/src/memory/Memory.ts"
    click Cache "https://github.com/bencbartlett/Overmind/blob/master/src/caching/GameCache.ts"
    click Console "https://github.com/bencbartlett/Overmind/blob/master/src/console/Console.ts"
    click Stats "https://github.com/bencbartlett/Overmind/blob/master/src/stats/stats.ts"
    click RoomPlanner "https://github.com/bencbartlett/Overmind/blob/master/src/roomPlanner/BasePlanner.ts"
    click CombatIntel "https://github.com/bencbartlett/Overmind/blob/master/src/intel/CombatIntel.ts"
    click Movement "https://github.com/bencbartlett/Overmind/blob/master/src/movement/Movement.ts"
    click TaskMgmt "https://github.com/bencbartlett/Overmind/blob/master/src/tasks/Task.ts"
    click Terminal "https://github.com/bencbartlett/Overmind/blob/master/src/logistics/TerminalNetwork.ts"
    click Link "https://github.com/bencbartlett/Overmind/blob/master/src/logistics/LinkNetwork.ts"
    click Spawn "https://github.com/bencbartlett/Overmind/blob/master/src/logistics/SpawnGroup.ts"
    click Trade "https://github.com/bencbartlett/Overmind/blob/master/src/logistics/TradeNetwork.ts"
    click HiveCluster "https://github.com/bencbartlett/Overmind/blob/master/src/hiveClusters/_HiveCluster.ts"

    %% Styling
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef ops fill:#2ecc71,stroke:#27ae60,color:white
    classDef support fill:#f1c40f,stroke:#f39c12,color:black
    classDef planning fill:#e74c3c,stroke:#c0392b,color:white
    classDef logistics fill:#9b59b6,stroke:#8e44ad,color:white

    %% Legend
    subgraph Legend
        L1["Core Control"]:::core
        L2["Operations"]:::ops
        L3["Support"]:::support
        L4["Planning"]:::planning
        L5["Logistics"]:::logistics
    end
```
