# efforg/rayhunter architecture

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

- Interactive diagram: https://gitdiagram.com/efforg/rayhunter
- Repository: https://github.com/efforg/rayhunter

## Overview

##### Main Components
- Daemon/Server (bin): This is the central executable that runs on the device. It handles:
– Starting the service and managing device interactions (e.g., capturing diagnostics, pcap logs, qmdl logs)
– Serving the Web UI by exposing a web server (note the static files under bin/static with HTML, CSS, JavaScript)
– Managing backend operations such as analysis, statistics, and configuration (files like config.rs, analysis.rs, server.rs, daemon.rs)
- Core Analysis & Utility Library (lib): Contains modular subcomponents that include:
– Various analysis modules (under lib/src/analysis/ like analyzer.rs, connection_redirect_downgrade.rs, etc.)
– Diagnostic tools (diag.rs, diag_device.rs)
– Parsers for file formats (pcap.rs, qmdl.rs, gsmtap_parser.rs)
– Utility functions shared with other binaries.
- Telecommunication Parser (telcom-parser): A dedicated crate for parsing ASN.1 specifications related to LTE/telecom protocols
– This includes definitions for EUTRA and PC5 protocols and supports the protocol-specific parsing logic.
- Ancillary Utilities:
– Rootshell: A small utility meant to spawn a root shell so that capture files and other system-critical files can be managed safely.
– Serial: Likely responsible for serial communication with the device (for instance, interfacing with the diag interface).
– Tools: A collection of scripts (e.g., asn1grep, nasparse, install-dev.sh) to aid in installation, debugging, and development.

##### Relationships and Interactions
- The primary daemon (from the “bin” crate) acts as the orchestrator. It uses the core library (from “lib”) for heavy lifting like analyzing diagnostic data.
- The web server, embedded within the daemon, serves the static UI assets. It provides endpoints for starting/stopping data captures and retrieving analysis results.
- The telcom-parser crate is used by the analysis modules when dealing with LTE RRC messages and ASN.1 definitions.
- The Serial module is likely used to communicate with the hardware’s diag interface, feeding raw data into the analysis pipeline.
- Rootshell is a supporting component used for performing privileged actions (e.g., cleanup of capture files) on the device.
- External interactions include:
- Communication over WiFi/USB (using adb forwarding) that allows a laptop or phone to interact with the web UI.
- Interaction with hardware (the Orbic device) via diagnostic channels.

##### Architectural Patterns and Design Principles
- Modular and multi-crate design: The project is clearly divided into separate Rust crates (bin, lib, rootshell, serial, telcom-parser, tools) to encapsulate functionality.
- Clear separation of concerns: The daemon handles runtime operations and the UI, while lib encapsulates core analysis logic and telcom-parser handles telecom-specific parsing.
- Extensibility: The use of modular analysis components (each analysis file in lib/src/analysis/) allows for easier expansion and testing.
- Deployment orientation: Installation scripts in “dist” and “tools” show that the project targets embedded deployments, with specific instructions for different platforms (Linux, macOS, Windows).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Backend Modules"
        D["Daemon/Server (bin)"]:::daemon
        L["Core Analysis & Parsing (lib)"]:::lib
        T["Telecommunication Parser (telcom-parser)"]:::telcom
        S["Serial Communication Module (serial)"]:::utilities
        R["Rootshell Utility (rootshell)"]:::utilities
        Tool["Ancillary Tools (tools)"]:::tools
    end

    subgraph "Frontend Modules"
        W["Web UI (bin/static)"]:::web
    end

    subgraph "External Entities"
        H["Hardware (Orbic Device)"]:::external
        C["Client Devices (WiFi/USB)"]:::external
    end

    H -->|"DiagIngest"| S
    S -->|"RawData"| D
    D -->|"Analysis"| L
    L -->|"Parsing"| T
    D -->|"HTTP_API"| W
    W -->|"AccessibleVia"| C
    D -->|"PrivilegedOps"| R
    Tool -->|"Support"| D

    click D "https://github.com/efforg/rayhunter/tree/main/bin/"
    click L "https://github.com/efforg/rayhunter/tree/main/lib/"
    click T "https://github.com/efforg/rayhunter/tree/main/telcom-parser/"
    click S "https://github.com/efforg/rayhunter/tree/main/serial/"
    click R "https://github.com/efforg/rayhunter/tree/main/rootshell/"
    click Tool "https://github.com/efforg/rayhunter/tree/main/tools/"
    click W "https://github.com/efforg/rayhunter/tree/main/bin/static"

    classDef daemon fill:#f9d5e5,stroke:#333,stroke-width:2px;
    classDef lib fill:#aed9e0,stroke:#333,stroke-width:2px;
    classDef telcom fill:#ffd3b6,stroke:#333,stroke-width:2px;
    classDef utilities fill:#dcedc1,stroke:#333,stroke-width:2px;
    classDef tools fill:#ffb6b9,stroke:#333,stroke-width:2px;
    classDef web fill:#c9d6e3,stroke:#333,stroke-width:2px;
    classDef external fill:#ffe066,stroke:#333,stroke-width:2px;
```
