# qsgs-fans/freekill architecture

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

- Interactive diagram: https://gitdiagram.com/qsgs-fans/freekill
- Repository: https://github.com/qsgs-fans/freekill

## Overview

##### Main Components
- Frontend/UI: Represented by the QML code (found in the “Fk” directory, as well as portions of “src/ui” and “client” folders) that builds the game interface. This part also includes assets like images (in “image”), audio (in “audio”), and localized language files.
- Game Logic & Scripting: The Lua modules under folders such as “lua/core”, “lua/server”, “lua/client” and additional packages (in the “packages” directory) make up the high-level game logic including card behaviors, rules, AI, and event systems.
- Server/Networking: The C++ code in “src/server” and “src/network” handles lobby management, room setup, socket communication (client and server sockets), and authentication. In parallel, Lua files in “lua/server” work on game logic as well as network requests.
- Backend/Framework Support: The C++ “core” side of the project (including the “src/freekill.cpp” and related files) integrates with Lua via SWIG (located in “src/swig”) to expose Lua-based game logic to the Qt/C++ runtime.
- Build & Deployment Infrastructure: Notice the presence of CMakeLists.txt files (at project root and in “src” and “test”), GitHub workflows, Docker configurations, and platform-specific projects (e.g., “android” folder). These indicate robust build and deployment pipelines for multiple platforms.

##### Relationships and Interactions
- The client C++ modules (in “src/client”) and the networking modules (in “src/network”) interact directly with the game server components (in “src/server”) to manage real-time game events, login/authentication, and game room management.
- The Lua server scripts work parallel to the C++ server modules, orchestrated via event handlers and network responses that are mediated by the underlying socket code.
- Build and deployment flows connect the source layers with the distribution assets (e.g., Android builds, Windows builds, and Docker containers).

##### Architectural Patterns and Design Principles
- Layered Architecture: Clearly separate the presentation layer (UI/QML), the application/game logic layer (Lua scripts and packages), and the system/network layer (C++ server modules and networking).
- Interoperability via SWIG: Emphasize the bridge that ties Lua scripting to C++ functionalities.
- Modularity: The directory structure (with distinct directories for “Fk”, “lua”, “packages”, “client”, “server”, etc.) implies a modular design where game enhancements (like additional skills or new generals) are isolated in their own packages.
- Cross-Platform Considerations: With separate directories and build scripts for Android, Windows, Docker, etc., show that the architecture supports multiple deployment targets.

##### Relevant Technologies/Frameworks
- Qt Framework (especially Qt Quick for UI and core C++ libraries for networking).
- Lua scripting for game logic.
- C++ for system-level operations.
- CMake and SWIG for build and integration.
- GitHub Workflows, Docker, and platform-specific scripts for continuous integration and deployment.

##### Detail
- Every element that plays a significant role is captured; do not shy away from splitting the architecture into subcomponents if necessary (e.g., separating networking into “client socket” and “server socket” submodules).
- Labels for interactions such as “API calls”, “event triggers”, “data synchronization”, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend/UI Layer
    subgraph "Frontend/UI"
        UI_FK["FK (QML & UI)"]:::frontend
        UI_SRC["src/ui (UI Backend)"]:::frontend
        ASSET_IMG["Images Asset"]:::asset
        ASSET_AUDIO["Audio Asset"]:::asset
        ASSET_LANG["Language Files"]:::asset
    end

    %% Game Logic & Scripting Layer
    subgraph "Game Logic & Scripting"
        LUA_CORE["lua/core (Game Core)"]:::lua
        LUA_SERVER["lua/server (Server Lua Logic)"]:::lua
        LUA_CLIENT["lua/client (Client Lua Logic)"]:::lua
        PACKAGES["packages (Game Packages)"]:::lua
    end

    %% Server/Networking Layer
    subgraph "Server/Networking"
        SERVER_CPP["src/server (C++ Server)"]:::server
        NETWORK_CPP["src/network (Network Modules)"]:::server
    end

    %% Backend/Framework Support Layer
    subgraph "Backend/Framework Support"
        FREEKILL["src/freekill.cpp (Core Integration)"]:::cpp
        SWIG["src/swig (SWIG Bridge)"]:::cpp
    end

    %% Build & Deployment Infrastructure
    subgraph "Build & Deployment Infrastructure"
        CMAKE["CMakeLists.txt (Build Scripts)"]:::infra
        GITHUB[".github/workflows (CI/CD Workflows)"]:::infra
        DOCKER["docker (Docker Config)"]:::infra
        ANDROID["android (Platform Build Scripts)"]:::infra
    end

    %% Interactions between Layers
    UI_FK -->|"callsLuaRoutines"| LUA_CORE
    UI_SRC -->|"interfacesWithLua"| LUA_CLIENT

    LUA_CLIENT -->|"triggersEvents"| SERVER_CPP
    LUA_SERVER -->|"handlesNetworkRequests"| NETWORK_CPP

    SERVER_CPP -->|"managesSessions"| NETWORK_CPP
    NETWORK_CPP -->|"syncsWithServer"| SERVER_CPP

    LUA_CORE -->|"exposedViaSWIG"| SWIG
    SWIG -->|"bridgesToCore"| FREEKILL

    %% UI Assets relationships
    UI_FK -->|"loads"| ASSET_IMG
    UI_FK -->|"loads"| ASSET_AUDIO
    UI_FK -->|"loads"| ASSET_LANG

    %% Build & Deployment relationships
    CMAKE -->|"buildsApplication"| FREEKILL
    GITHUB -->|"triggersBuilds"| CMAKE
    DOCKER -->|"buildsImage"| CMAKE
    ANDROID -->|"buildsPlatformVersion"| CMAKE

    %% Integration between Lua server logic and C++ server modules
    LUA_SERVER ---|"integratesWith"| SERVER_CPP

    %% Click Events
    click UI_FK "https://github.com/qsgs-fans/freekill/tree/master/Fk/"
    click UI_SRC "https://github.com/qsgs-fans/freekill/tree/master/src/ui/"
    click ASSET_IMG "https://github.com/qsgs-fans/freekill/tree/master/image/"
    click ASSET_AUDIO "https://github.com/qsgs-fans/freekill/tree/master/audio/"
    click ASSET_LANG "https://github.com/qsgs-fans/freekill/tree/master/lang/"
    click LUA_CORE "https://github.com/qsgs-fans/freekill/tree/master/lua/core/"
    click LUA_SERVER "https://github.com/qsgs-fans/freekill/tree/master/lua/server/"
    click LUA_CLIENT "https://github.com/qsgs-fans/freekill/tree/master/lua/client/"
    click PACKAGES "https://github.com/qsgs-fans/freekill/tree/master/packages/"
    click SERVER_CPP "https://github.com/qsgs-fans/freekill/tree/master/src/server/"
    click NETWORK_CPP "https://github.com/qsgs-fans/freekill/tree/master/src/network/"
    click FREEKILL "https://github.com/qsgs-fans/freekill/blob/master/src/freekill.cpp"
    click SWIG "https://github.com/qsgs-fans/freekill/tree/master/src/swig/"
    click CMAKE "https://github.com/qsgs-fans/freekill/blob/master/CMakeLists.txt"
    click GITHUB "https://github.com/qsgs-fans/freekill/tree/master/.github/workflows/"
    click DOCKER "https://github.com/qsgs-fans/freekill/tree/master/docker/"
    click ANDROID "https://github.com/qsgs-fans/freekill/tree/master/android/"

    %% Styling Classes
    classDef frontend fill:#9fdae1,stroke:#333,stroke-width:2px;
    classDef asset fill:#c1e1c1,stroke:#333,stroke-width:2px;
    classDef lua fill:#ffebaa,stroke:#333,stroke-width:2px;
    classDef server fill:#f9b3d1,stroke:#333,stroke-width:2px;
    classDef cpp fill:#f3f3a1,stroke:#333,stroke-width:2px;
    classDef infra fill:#d9d2e9,stroke:#333,stroke-width:2px;
```
