# matsuridayo/nekoray architecture

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

- Interactive diagram: https://gitdiagram.com/matsuridayo/nekoray
- Repository: https://github.com/matsuridayo/nekoray

## Overview

##### Project type and purpose
- The user interacts with a Qt-based frontend to configure and manage multiple proxy protocols (SOCKS, HTTP(S), Shadowsocks, VMess, VLESS, Trojan, TUIC, etc.).

##### File structure
- Top-level build and config: CMakeLists.txt, .github/workflows, cmake/, libs/ (build & deploy scripts).
- Frontend/UI (C++/Qt):
- main/, ui/, res/, translations/ (all *.cpp, *.hpp, *.ui, resource files)
- sys/ (platform abstractions for Windows/Linux)
- Business logic & data:
- db/ (ConfigBuilder, Database, ProxyEntity, TrafficLooper)
- fmt/ (serializing internal “Beans” to core config objects)
- RPC layer:
- rpc/ (gRPC client stubs and helpers gRPC.cpp/h)
- Third-party libs in 3rdparty/ (Qv2ray, protobuf, yaml-cpp, zxing, QHotkey, etc.)
- Go backend:
- go/grpc_server (proto definitions, generated Go stubs)
- go/cmd/updater (self-update service)
- Tests & docs: test/, docs/, README.md

##### README for additional insights
- Lists supported protocols, subscription parsing, run flags.
- References technical docs (RunFlags.md, Build instructions).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraphs and modules
    subgraph "Qt GUI Application"
        direction TB
        UI["UI Layer"]:::frontend
        Main["Business Logic - Main Entry"]:::business
        DBLogic["Business Logic - Data & Config"]:::business
        FMT["Bean Formatters"]:::business
        RPCClient["RPC Client"]:::rpc
        Platform["Platform Abstractions"]:::platform
        Resources["Resources & Themes"]:::resources
        ThirdParty["3rdparty Libraries"]:::thirdparty
    end

    subgraph "Go Backend Services"
        direction TB
        CoreService["Core Service (gRPC Server & Orchestrator)"]:::backend
        Updater["Updater Service"]:::backend
        GRPCDefs["gRPC Proto Definitions & Helpers"]:::backend
    end

    subgraph "External Components"
        direction TB
        SingBox["sing-box Proxy Engine"]:::external
        Database["Local Storage (SQLite)"]:::database
    end

    %% Connections
    UI -->|"user config"| Main
    Main -->|"build Beans"| FMT
    FMT -->|"config objects"| RPCClient
    RPCClient -->|"gRPC ApplyConfig()"| CoreService
    CoreService -->|"store/retrieve"| Database
    CoreService -->|"launch/control"| SingBox
    CoreService -->|"gRPC Stream Metrics"| RPCClient
    RPCClient -->|"metrics"| UI
    Updater -->|"update core"| CoreService
    GRPCDefs --> CoreService
    RPCClient --> GRPCDefs

    %% Click Events
    click UI "https://github.com/matsuridayo/nekoray/tree/main/ui/"
    click Main "https://github.com/matsuridayo/nekoray/tree/main/main/"
    click DBLogic "https://github.com/matsuridayo/nekoray/tree/main/db/"
    click FMT "https://github.com/matsuridayo/nekoray/tree/main/fmt/"
    click RPCClient "https://github.com/matsuridayo/nekoray/tree/main/rpc/"
    click Platform "https://github.com/matsuridayo/nekoray/tree/main/sys/"
    click Resources "https://github.com/matsuridayo/nekoray/tree/main/res/"
    click ThirdParty "https://github.com/matsuridayo/nekoray/tree/main/3rdparty/"
    click CoreService "https://github.com/matsuridayo/nekoray/tree/main/go/cmd/nekobox_core/"
    click Updater "https://github.com/matsuridayo/nekoray/tree/main/go/cmd/updater/"
    click GRPCDefs "https://github.com/matsuridayo/nekoray/tree/main/go/grpc_server/"
    click Database "https://github.com/matsuridayo/nekoray/blob/main/db/Database.cpp"
    click SingBox "https://github.com/matsuridayo/nekoray/tree/main/go/cmd/nekobox_core/"

    %% Styles
    classDef frontend fill:#FFE4B5,stroke:#D2691E,color:#000
    classDef business fill:#E6E6FA,stroke:#9370DB,color:#000
    classDef rpc fill:#AFEEEE,stroke:#20B2AA,color:#000
    classDef platform fill:#FFFACD,stroke:#FFD700,color:#000
    classDef resources fill:#F0FFF0,stroke:#32CD32,color:#000
    classDef thirdparty fill:#F5F5DC,stroke:#8B4513,color:#000
    classDef backend fill:#D3D3D3,stroke:#696969,color:#000
    classDef database fill:#FFF0F5,stroke:#C71585,color:#000
    classDef external fill:#F0F8FF,stroke:#4682B4,color:#000
```
