# peter-fayez95/lux-ai architecture

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

- Interactive diagram: https://gitdiagram.com/peter-fayez95/lux-ai
- Repository: https://github.com/peter-fayez95/lux-ai

## Overview

##### Main Components Identification

The project follows a modular architecture with distinct services and controllers. Here's how to represent the main components:

a) Core Game Integration Layer:
- Game_map.py, game_objects.py, and game_constants.py as core components

b) Strategic Modules (Middle Layer):
- Cluster management system
- Mission control system
- Resource management
- Unit management
- Enemy tracking
- Services

c) Agent Layer (Top Level):
- Main agent.py as the entry point
- Controller components that orchestrate the services

##### Component Relationships

a) Data Flow:
- From lux game engine → agent.py
- agent.py → various controllers
- controllers → corresponding services
- services → helper functions

b) Dependencies:
- How Mission Controller depends on other services
- Resource and unit service interactions
- Cluster controller's relationship with the map service

**[Component Styling]**
- Use rectangles for service modules (Resources, Units, Enemy, Map)
- Use hexagons for controllers (clusterController, MissionController)
- Use circles for helper functions

**[Layout]**
**Top Layer:**
- [agent.py (Main Entry Point)]
- ↓
**Middle Layer:**
- [Controllers]
- MissionController
- clusterController
- resourceController
- ↓
**Service Layer:**
- [Services]
- mapService
- enemyService
- resourceService
- unitsService
- ↓
**Foundation Layer:**
- [Lux Game Engine]
- game.py
- game_map.py
- game_objects.py
- constants.py

##### Important Architectural Patterns to Highlight

- Service-oriented architecture with clear separation of concerns
- Controller-Service pattern for resource management
- Event-driven game loop architecture
- Modular design with independent services

##### Technical Details

a) Core Components:
- Lux game engine integration
- Mission system
- Clustering system
- Resource management
- Unit management
- Enemy tracking
- Management

b) Support Systems:
- Helper functions
- Constants and configuration
- Testing framework integration

##### Interaction Flows

Critical flows:
- Game state updates from lux engine → agent
- Strategic decisions in MissionController
- Resource allocation flows
- Unit command flows
- Enemy interaction handling

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Legend
        L1[Service Module]
        L2{{Controller}}
        L3((Helper))
        L4[/Entry Point/]
        L5[(Game Engine)]
    end

    subgraph "Agent Layer"
        Agent[/agent.py/]:::entry
        click Agent "https://github.com/Peter-Fayez95/Lux-AI/blob/main/agent.py"
    end

    subgraph "Controller Layer"
        MissionCtrl{{Mission Controller}}:::controller
        ClusterCtrl{{Cluster Controller}}:::controller
        ResourceCtrl{{Resource Controller}}:::controller
        click MissionCtrl "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Missions/MissionController.py"
        click ClusterCtrl "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Cluster/clusterController.py"
        click ResourceCtrl "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Resources/resourceController.py"
    end

    subgraph "Service Layer"
        MapService[Map Service]:::service
        EnemyService[Enemy Service]:::service
        ResourceService[Resource Service]:::service
        UnitService[Unit Service]:::service
        click MapService "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Map/mapService.py"
        click EnemyService "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Enemy/enemyService.py"
        click ResourceService "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Resources/resourceService.py"
        click UnitService "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Units/unitsService.py"
    end

    subgraph "Strategic Components"
        ClusterSystem[Cluster System]:::component
        MissionSystem[Mission System]:::component
        MissionConst[Mission Constants]:::component
        click ClusterSystem "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Cluster/Cluster.py"
        click MissionSystem "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Missions/Mission.py"
        click MissionConst "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Missions/constants.py"
    end

    subgraph "Support Systems"
        HelperFunctions((Helper Functions)):::helper
        WeightsConfig((Weights Configuration)):::helper
        click HelperFunctions "https://github.com/Peter-Fayez95/Lux-AI/blob/main/helperFunctions/helper_functions.py"
        click WeightsConfig "https://github.com/Peter-Fayez95/Lux-AI/blob/main/Weights/Cluster.py"
    end

    subgraph "Game Engine Layer"
        GameEngine[(Game Engine)]:::engine
        GameMap[(Game Map)]:::engine
        GameObjects[(Game Objects)]:::engine
        GameConstants[(Game Constants)]:::engine
        click GameEngine "https://github.com/Peter-Fayez95/Lux-AI/blob/main/lux/game.py"
        click GameMap "https://github.com/Peter-Fayez95/Lux-AI/blob/main/lux/game_map.py"
        click GameObjects "https://github.com/Peter-Fayez95/Lux-AI/blob/main/lux/game_objects.py"
        click GameConstants "https://github.com/Peter-Fayez95/Lux-AI/blob/main/lux/game_constants.py"
    end

    %% Relationships
    GameEngine & GameMap & GameObjects & GameConstants --> Agent
    Agent --> MissionCtrl & ClusterCtrl & ResourceCtrl
    
    MissionCtrl --> MapService & EnemyService
    ClusterCtrl --> MapService & ClusterSystem
    ResourceCtrl --> ResourceService & UnitService
    
    MapService & EnemyService & ResourceService & UnitService --> HelperFunctions
    ClusterSystem --> WeightsConfig
    MissionSystem --> MissionConst
    
    MissionCtrl --> MissionSystem
    ClusterCtrl --> ClusterSystem

    %% Styles
    classDef service fill:#a8d5e5
    classDef controller fill:#ffb6c1
    classDef helper fill:#98fb98
    classDef engine fill:#deb887
    classDef entry fill:#ff9966
    classDef component fill:#dda0dd
```
