# geph-official/geph5 architecture

> Architecture diagram of the GitHub repository geph-official/geph5, 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/geph-official/geph5
- Repository: https://github.com/geph-official/geph5

## Overview

##### Main components
- Binaries:
– geph5-client and geph5-client-gui: The client interfaces that initiate sessions and interact with the broker. Note that the GUI client directly calls Rust protocol libraries.
– geph5-broker: The central authentication and routing server. It now exposes a JSON-RPC API (with ed25519 signatures for integrity-critical responses) and acts as the intermediary for client authentication and route establishment.
– geph5-bridge: A component that connects the client and exit by providing transport bridges using multiplexed TCP streams.
– geph5-exit: Handles the exit side of connections (similar in role to a network proxy/VPN exit point).
- Libraries: There are multiple libraries (e.g., sillad, picomux, nanorpc, nano-influxdb, arc-writer, etc.) that provide functionality, communication protocols, and networking abstractions shared across binaries.

##### Relationships and interactions
- Transport Mechanism: Within the bridge component (and parts of the client/VPN lock in geph5-client), highlight that data is sent over multiplexed TCP streams instead of relying on unreliable packet-based transports.

##### Important architectural patterns or design principles
- Config-Driven Architecture: Emphasize that the project takes a config file–driven approach rather than relying on extensive command-line parameters.
- Simplified Session Handling: Note that sessions are created and used until breakage and then restarted, rather than relying on complex “hot-swap” mechanisms.
- JSON-RPC and Ed25519 Signature Use: Explain that the broker uses a simple JSON-RPC API for communication and cryptographic measures for security-critical responses.
- Clear Separation of Concerns: The division between authentication (broker), transport bridging (bridge), final exit functionality (exit), and client logic is a core design principle.

– Workspace container dividing “Binaries” and “Libraries.”
– A separate Libraries node listing shared protocol and network libraries (for instance, sillad, picomux, nanorpc-sillad, etc.).
– From Client to Broker (session initiation and control traffic).
– From Broker to Bridge and Exit (to set up and manage routes).
- Labels for each node indicating its primary responsibilities (e.g., “Broker – Central JSON-RPC API service with session management”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Workspace["Workspace Boundary"]:::workspace
    click Workspace "https://github.com/geph-official/geph5/blob/master/Cargo.toml"

    subgraph "Cargo Workspace"
        subgraph "Binaries"
            geph5_client["geph5-client<br>(Initiates session)"]:::binary
            click geph5_client "https://github.com/geph-official/geph5/tree/master/binaries/geph5-client"
            geph5_client_gui["geph5-client-gui<br>(GUI Client using protocol libraries)"]:::binary
            click geph5_client_gui "https://github.com/geph-official/geph5/tree/master/binaries/geph5-client-gui"
            geph5_broker["geph5-broker<br>(Central JSON-RPC API & session management)"]:::binary
            click geph5_broker "https://github.com/geph-official/geph5/tree/master/binaries/geph5-broker"
            geph5_bridge["geph5-bridge<br>(Multiplexed TCP transport bridge)"]:::binary
            click geph5_bridge "https://github.com/geph-official/geph5/tree/master/binaries/geph5-bridge"
            geph5_exit["geph5-exit<br>(VPN exit handling)"]:::binary
            click geph5_exit "https://github.com/geph-official/geph5/tree/master/binaries/geph5-exit"
        end
        subgraph "Libraries"
            sillad["sillad<br>(Protocol support)"]:::library
            click sillad "https://github.com/geph-official/geph5/tree/master/libraries/sillad"
            picomux["picomux<br>(Networking abstraction)"]:::library
            click picomux "https://github.com/geph-official/geph5/tree/master/libraries/picomux"
            nanorpc["nanorpc-sillad<br>(RPC support)"]:::library
            click nanorpc "https://github.com/geph-official/geph5/tree/master/libraries/nanorpc-sillad"
            nanoInflux["nano-influxdb<br>(InfluxDB integration)"]:::library
            click nanoInflux "https://github.com/geph-official/geph5/tree/master/libraries/nano-influxdb"
            arcWriter["arc-writer<br>(Logging helper)"]:::library
            click arcWriter "https://github.com/geph-official/geph5/tree/master/libraries/arc-writer"
        end
    end

    %% Workspace Boundary connections to binaries (conceptually contained)
    Workspace --> geph5_client
    Workspace --> geph5_client_gui
    Workspace --> geph5_broker
    Workspace --> geph5_bridge
    Workspace --> geph5_exit

    %% Session Lifecycle: Clients initiate session with Broker
    geph5_client -->|"init_session"| geph5_broker
    geph5_client_gui -->|"init_session"| geph5_broker

    %% Broker manages routing: Forwarding to Bridge and Exit
    geph5_broker -->|"route_setup"| geph5_bridge
    geph5_broker -->|"route_setup"| geph5_exit

    %% Library Dependencies (dashed arrows)
    geph5_client_gui ---|"uses"| sillad
    geph5_broker ---|"uses_RPC"| nanorpc
    geph5_bridge ---|"uses_net"| picomux
    geph5_bridge ---|"uses_influx"| nanoInflux
    geph5_exit ---|"uses_logging"| arcWriter

    %% Styles
    classDef workspace fill:#FFE4B5,stroke:#333,stroke-width:2px;
    classDef binary fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef library fill:#90EE90,stroke:#333,stroke-width:2px;
```
