# lmeszinc/starrailcopilot architecture

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

- Interactive diagram: https://gitdiagram.com/lmeszinc/starrailcopilot
- Repository: https://github.com/lmeszinc/starrailcopilot

## Overview

##### Project Overview and Architecture Type
- This is a hybrid automation and UI application for automating game interactions in Star Rail.
- It is a full-stack application in that it has a core automation engine (the “backend”) and an Electron/web-based UI (the “frontend”). In addition, there are device connectivity and system deployment components.
- The project is modular with clear separations, built on a mature but somewhat “legacy” Alas framework that has evolved considerably.

##### Main Components
a. Automation/Core Engine:
- Located in directories like “module” and “tasks” – these contain the core logic, task definitions (daily, combat, dungeon, rogue, etc.), and automation routines.
- Submodules for configuration (module/config), device management (module/device), logging (module/logger), daemon processes (module/daemon) and error/exception handling.
b. Assets Management:
- A robust “assets” directory holds language-specific UI elements, images, and templates used by the automation tasks and possibly by the GUI.
c. User Interface:
- “webapp” folder: It contains an Electron-based GUI with separate “packages” for main (backend-like logic), renderer (frontend components with Vue or similar), and preload scripts.
- The UI components give a dashboard to configure tasks, view reports, and monitor emulator/game performance.
d. Device and Emulator Interaction Layer:
- Contained in “module/device” and corresponding binaries in “bin” (e.g., DroidCast, scrcpy, ascreencap, maatouch) which handle connection to simulators and control input.
- This layer communicates with emulators ensuring the game window can be captured and controlled.
e. Deployment/Installation:
- “deploy” directory holds scripts and configuration to package and deploy the project (e.g., installer scripts, configuration for Windows deployment, git_over_cdn support).
f. Development & Utility Tools:
- “dev_tools” for extracting button templates and keywords (useful for image detection and OCR tasks).
- OCR functionalities found inside “module/ocr” that are used for image-to-text conversion.
g. Configuration & Localization:
- Configuration files in “module/config” handle dynamic settings and internationalization (i18n) support, as seen with language files in assets and config modules.

##### How the Components Interact
- The automation engine (modules and tasks) is the core that carries out the game automation logic. It interacts with:
– The device/emulator layer to capture screenshots, send control commands, and process game states.
– The configuration layer to load user settings, localization details, and update internal state.
– The assets management system to fetch templates used for pattern matching and image recognition.
- The webapp (Electron frontend) communicates with the core automation engine via inter-process communication channels (IPC in Electron, possibly using FastAPI in “module/webui”) to provide real-time status, accept user commands, and output logs.
- Deployment scripts are used to set up the runtime environment, ensuring that all binaries, configurations, and modules are correctly placed and integrated.
- Utility scripts and development tools help maintain and update assets & keywords; they are essentially supporting components in the overall toolchain.

##### Architectural Patterns and Design Principles
- Modular design: The project cleanly separates functionality into tasks, modules, assets, config, and UI.
- Layered architecture: There is a clear data/control flow underlying the layers:
– The bottom layer is device and asset management (handling emulator/simulator interaction).
– The core (modules/tasks) forms the business logic and automation engine.
– The top layer is the user interface (Electron app/webapp) which communicates with the core.
- Configuration and Localization handling: Using configuration generators and i18n file support.
- Separation of concerns: Each “task” (like combat, dungeon, login, rogue, etc.) has its own folder and asset management, making it easier to debug and maintain.
- External integrations: The inclusion of external binaries (e.g., scrcpy, DroidCast) and integration with cloud game support.

▪ Each component should have clear labels (names matching the directory structure like “module/config”, “tasks/dungeon”, “webapp/packages/renderer”).
– Data/control flow between the UI and core automation engine.
– Command flow from the core to device interfaces (via modules/device).
– The utilization of assets and config flows that enable localization and template matching.
– Presentation layer (Electron/webapp components) versus business logic (tasks/modules) versus infrastructure (device layer, external binaries).
▪ If possible, annotate with notes on any patterns (like MVC separation evident in how tasks call into config and device modules, and UI interacts via IPC).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend/UI Layer"
        webapp("webapp"):::frontend
    end

    subgraph "Core Automation Engine"
        moduleCore("module (Core Logic)"):::core
        tasks("tasks"):::core
        moduleConfig("module/config"):::config
        moduleOCR("module/ocr"):::core
        assets("assets"):::assets
    end

    subgraph "Device/Emulator Interaction"
        moduleDevice("module/device"):::device
        bin("bin"):::device
    end

    subgraph "Supporting Tools"
        deploy("deploy"):::support
        devTools("dev_tools"):::support
    end

    %% Data/control flows
    webapp -->|"commandIPC"| moduleCore
    moduleCore -->|"statusUpdates"| webapp

    moduleCore -->|"executes"| tasks
    moduleCore -->|"loadsConfig"| moduleConfig
    moduleCore -->|"usesAssets"| assets
    tasks -->|"triggersOCR"| moduleOCR
    moduleCore -->|"sendsDeviceCmd"| moduleDevice
    moduleDevice -->|"invokes"| bin
    bin -->|"sendsResponse"| moduleDevice

    devTools -->|"updatesAssets"| assets
    deploy -->|"packagesSystem"| moduleCore

    %% Click Events
    click webapp "https://github.com/lmeszinc/starrailcopilot/tree/master/webapp"
    click moduleCore "https://github.com/lmeszinc/starrailcopilot/tree/master/module"
    click tasks "https://github.com/lmeszinc/starrailcopilot/tree/master/tasks"
    click assets "https://github.com/lmeszinc/starrailcopilot/tree/master/assets"
    click moduleDevice "https://github.com/lmeszinc/starrailcopilot/tree/master/module/device"
    click bin "https://github.com/lmeszinc/starrailcopilot/tree/master/bin"
    click deploy "https://github.com/lmeszinc/starrailcopilot/tree/master/deploy"
    click devTools "https://github.com/lmeszinc/starrailcopilot/tree/master/dev_tools"
    click moduleConfig "https://github.com/lmeszinc/starrailcopilot/tree/master/module/config"

    %% Styles
    classDef frontend fill:#cef,stroke:#036,stroke-width:2px;
    classDef core fill:#cfc,stroke:#090,stroke-width:2px;
    classDef config fill:#fcf,stroke:#909,stroke-width:2px;
    classDef assets fill:#ff9,stroke:#996,stroke-width:2px;
    classDef device fill:#fbb,stroke:#900,stroke-width:2px;
    classDef support fill:#eee,stroke:#666,stroke-width:2px;
```
