# juliuskreutz/stardb-exporter architecture

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

- Interactive diagram: https://gitdiagram.com/juliuskreutz/stardb-exporter
- Repository: https://github.com/juliuskreutz/stardb-exporter

## Overview

##### Project type and purpose
- From the file tree and README, this is a single‑binary Rust CLI/TUI application (“stardb‑exporter”) whose job is to sniff network packets from Genshin Impact (GI) or Honkai: Star Rail (HSR) via libpcap, decode their game‑specific protocols, and export the resulting data (automatically copying it to the clipboard).

##### File structure
- Top‑level:
- Cargo.toml, build.rs, flake.nix → Build system and reproducible environment
- src/main.rs, src/app.rs → Application entry point and core orchestrator
- src/games/… → Protocol parsers for each game (gi.rs, hsr.rs) plus shared parsing glue (mod.rs)
- src/ui/… → TUI screens and widgets (login, menu, waiting, pulls, achievements, error, etc.)
- keys/… → Protocol decryption keys for each game
- External integration:
- libpcap (via system package/cap_net_raw capability) for packet capture
- Clipboard API (Rust crate) to copy export JSON to the user’s clipboard

##### README for additional insights
- Uses raw 802.11 (monitor mode) or WinPcap in WinPcap API‑compatible mode
- Flow: user launches exporter, enters monitor mode, app reports “Device ready~!”, user triggers game action, exporter grabs data and copies it to clipboard, user pastes into stardb.gg/import.

a. Main components
1. CLI/TUI Frontend
- Responsible for all on‑screen interaction (menus, status, errors).
2. Application Core (State Machine)
- Manages lifecycle: initialization → device ready → capture → parsing → export → done/error.
3. Network Capture Layer
- libpcap binding that opens the interface in monitor/raw mode and feeds raw packets.
4. Protocol Parsers
- Game‑specific modules (GI, HSR) that take raw packet streams, decrypt and deserialize messages.
5. Output/Export
- Serializes parsed data into JSON (or internal format) and pushes to clipboard.
6. Configuration & Keys
- Key store loaded at startup to decrypt game traffic.
7. Build/Deploy (auxiliary)
- Cargo, build.rs, flake.nix for reproducible builds; GitHub Actions workflows for clippy & release.

b. Relationships & interactions
- User → CLI/TUI Frontend (input events)
- Frontend ↔ Application Core (dispatch user actions & render state)
- Core → Network Capture Layer (start/stop sniffing)
- Layer → Protocol Parsers (stream of raw packets)
- Parsers → Application Core (parsed game data events)
- Core → Frontend (update UI screens on new data)
- Core → Output/Export (on completion, serialize & copy to clipboard)

c. Architectural patterns/design principles
- Separation of concerns: UI, core state machine, capture, parsing, export
- Pluggable parsers: Each game has its own parser module under src/games
- Theme abstraction: UI visuals pulled from src/themes at runtime
- Single‑process, event‑driven architecture

d. Key technologies/frameworks/libraries
- Rust/Cargo (build & dependency management)
- libpcap (via pcap crate) for packet capture
- TUI toolkit (e.g., tui-rs + crossterm) for terminal UI
- Clipboard crate for cross‑platform clipboard access
- Nix (flake.nix) for reproducible development environment

##### Elements
- Another for “UI” (Frontend, Themes)
- Another for “External Dependencies” (libpcap, OS capabilities, clipboard)

##### Final advice
- Be as granular as helpful: split UI into screens if needed, show theme loading as separate step.
- Build tools (Cargo, GitHub Actions, flake.nix) outside the runtime path but visibly connected to the source directory to illustrate CI/CD boundaries.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User(("User")):::external

    %% UI Frontend
    subgraph "UI (Frontend)"
        UIDir["src/ui/"]:::ui
        UIMod["mod.rs"]:::ui
        Login["login.rs"]:::ui
        Menu["menu.rs"]:::ui
        Waiting["waiting.rs"]:::ui
        Pulls["pulls.rs"]:::ui
        PullMenu["pull_menu.rs"]:::ui
        Achievements["achievements.rs"]:::ui
        ErrorUI["error.rs"]:::ui
        Header["header.rs"]:::ui
        GameUI["game.rs"]:::ui
    end

    %% Themes
    subgraph "Themes"
        ThemeDir["src/themes/"]:::theme
        Classic["classic.rs"]:::theme
        Dark["dark.rs"]:::theme
        Light["light.rs"]:::theme
        ThemeMod["mod.rs"]:::theme
    end

    %% Application Core
    subgraph "Application Core"
        MainRs["main.rs"]:::core
        AppRs["app.rs"]:::core
    end

    %% Network Capture Layer
    Capture["Network Capture (libpcap)"]:::core

    %% Protocol Parsers
    subgraph "Protocol Parsers"
        GamesDir["src/games/"]:::core
        GamesMod["mod.rs"]:::core
        GIParser["gi.rs"]:::core
        HSRParser["hsr.rs"]:::core
    end

    %% Configuration & Keys
    subgraph "Config & Keys"
        KeysDir["keys/"]:::config
        GIKeys["gi.json"]:::config
        HSRKeys["hsr.json"]:::config
    end

    %% Output/Export
    Export["Serialization & Clipboard"]:::core

    %% External Dependencies
    subgraph "External Dependencies"
        Libpcap["libpcap"]:::external
        OSRaw["OS CAP_NET_RAW"]:::external
        ClipboardCrate["clipboard crate"]:::external
        TUICrate["tui-rs + crossterm"]:::external
        PcapCrate["pcap crate"]:::external
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        CargoToml["Cargo.toml"]:::build
        BuildRs["build.rs"]:::build
        FlakeNix["flake.nix"]:::build
        FlakeLock["flake.lock"]:::build
        ClippyCI[".github/workflows/clippy.yml"]:::build
        ReleaseCI[".github/workflows/release.yml"]:::build
    end

    %% Relationships
    User -->|interacts| UIDir
    UIDir -->|uses screens| UIMod
    UIDir --> Login
    UIDir --> Menu
    UIDir --> Waiting
    UIDir --> Pulls
    UIDir --> PullMenu
    UIDir --> Achievements
    UIDir --> ErrorUI
    UIDir --> Header
    UIDir --> GameUI
    UIDir -->|applies theme| ThemeDir
    ThemeDir --> Classic
    ThemeDir --> Dark
    ThemeDir --> Light
    ThemeDir --> ThemeMod

    UIDir -->|"dispatch actions"| MainRs
    MainRs --> AppRs
    AppRs --> Capture
    Capture -->|PacketEvent| GamesDir
    GamesDir --> GamesMod
    GamesDir --> GIParser
    GamesDir --> HSRParser
    GIKeys -.->|decrypts| GIParser
    HSRKeys -.->|decrypts| HSRParser
    KeysDir --> GIKeys
    KeysDir --> HSRKeys
    GamesDir -->|parsed events| AppRs
    AppRs -->|update UI| UIDir
    AppRs -->|CopyToClipboard| Export
    Export --> ClipboardCrate
    AppRs --> PcapCrate
    PcapCrate --> Libpcap
    Libpcap --> OSRaw
    UIDir --> TUICrate

    %% Build connections
    CargoToml --> MainRs
    BuildRs --> MainRs
    FlakeNix --> MainRs
    FlakeLock --> FlakeNix
    ClippyCI --> CargoToml
    ReleaseCI --> CargoToml

    %% Click Events
    click UIDir "https://github.com/juliuskreutz/stardb-exporter/tree/master/src/ui/"
    click UIMod "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/ui/mod.rs"
    click Login "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/ui/login.rs"
    click Menu "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/ui/menu.rs"
    click Waiting "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/ui/waiting.rs"
    click Pulls "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/ui/pulls.rs"
    click PullMenu "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/ui/pull_menu.rs"
    click Achievements "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/ui/achievements.rs"
    click ErrorUI "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/ui/error.rs"
    click Header "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/ui/header.rs"
    click GameUI "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/ui/game.rs"

    click ThemeDir "https://github.com/juliuskreutz/stardb-exporter/tree/master/src/themes/"
    click Classic "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/themes/classic.rs"
    click Dark "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/themes/dark.rs"
    click Light "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/themes/light.rs"
    click ThemeMod "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/themes/mod.rs"

    click MainRs "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/main.rs"
    click AppRs "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/app.rs"

    click GamesDir "https://github.com/juliuskreutz/stardb-exporter/tree/master/src/games/"
    click GamesMod "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/games/mod.rs"
    click GIParser "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/games/gi.rs"
    click HSRParser "https://github.com/juliuskreutz/stardb-exporter/blob/master/src/games/hsr.rs"

    click KeysDir "https://github.com/juliuskreutz/stardb-exporter/tree/master/keys/"
    click GIKeys "https://github.com/juliuskreutz/stardb-exporter/blob/master/keys/gi.json"
    click HSRKeys "https://github.com/juliuskreutz/stardb-exporter/blob/master/keys/hsr.json"

    click CargoToml "https://github.com/juliuskreutz/stardb-exporter/blob/master/Cargo.toml"
    click BuildRs "https://github.com/juliuskreutz/stardb-exporter/blob/master/build.rs"
    click FlakeNix "https://github.com/juliuskreutz/stardb-exporter/blob/master/flake.nix"
    click FlakeLock "https://github.com/juliuskreutz/stardb-exporter/blob/master/flake.lock"
    click ClippyCI "https://github.com/juliuskreutz/stardb-exporter/blob/master/.github/workflows/clippy.yml"
    click ReleaseCI "https://github.com/juliuskreutz/stardb-exporter/blob/master/.github/workflows/release.yml"

    %% Styles
    classDef ui fill:#B3E5FC,stroke:#0288D1,color:#000;
    classDef theme fill:#FFF9C4,stroke:#FBC02D,color:#000;
    classDef core fill:#C8E6C9,stroke:#388E3C,color:#000;
    classDef external fill:#FFE0B2,stroke:#F57C00,color:#000;
    classDef build fill:#E1BEE7,stroke:#8E24AA,color:#000;
    classDef config fill:#FFCDD2,stroke:#D32F2F,color:#000;
```
