# streetpea/chiaki-ng architecture

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

- Interactive diagram: https://gitdiagram.com/streetpea/chiaki-ng
- Repository: https://github.com/streetpea/chiaki-ng

## Overview

##### Project type and purpose
- chiaki-ng is an open-source, cross-platform remote-play client for PS4 and PS5.
- It provides a core C library implementing the PlayStation Remote Play protocol, plus multiple front-end applications (GUI, CLI, Android, Switch, Steam Deck).

##### Main components
a. Core Library (lib/)
- Implements discovery, authentication, streaming protocol, congestion control, FEC, encoding/decoding interfaces.
- Uses external codec/network libs: FFmpeg, Opus, SpeexDSP, libcurl, Nanopb, etc.
b. Front-ends
- GUI (gui/): Qt/QML C++ application that calls the core library, handles UI, session management, input mapping.
- CLI (cli/): command-line interface built on the core library for headless use.
- Android App (android/): Kotlin+JNI layer calls core library native code for discover, streaming, rendering (via Oboe, native video decoders).
- Nintendo Switch (switch/): native C++ app using core library, custom GUI.
- Steam Deck Native (steamdeck_native/) & setsu/: native demos for haptics/motion, input support on Steam Deck.
c. External Services
- PlayStation Network (public authentication endpoints).
- Hole-punch token servers (scripts/holepunch).
d. Build & Deployment Layers
- CMake build system (root CMakeLists + per-module CMakeLists).
- CI/CD pipelines (.github/workflows and .builds).
- Packaging scripts (scripts/* for AppImage, Flatpak, Docker).

##### Relationships and interactions
- Front-ends → Core Library: all user-facing apps invoke the core API for discovery, auth, session start/stop.
- Core Library ↔ PSN Endpoint: REST calls for login, token refresh.
- Core Library ↔ Discovery Service: UDP broadcast/discovery, hole-punch negotiation with token servers.
- Core Library ↔ Streaming Endpoint: encrypted TCP/UDP connection for video/audio packets.
- Core Library → FFmpeg/Opus: demux/decoding of video/audio packets.
- Front-ends → Rendering/Input APIs:
- GUI: Qt Quick/QML engine for video rendering, user input events.
- Android: Android UI + Oboe for audio, SurfaceView for video, touch control rendering.
- Switch: platform SDK for UI and input mapping.
- Build System orchestrates dependency discovery, compile/link across all targets.

##### Architectural patterns and design principles
- Layered architecture:
- Platform-agnostic core library (C, pure logic)
- Platform-specific adapters (JNI, Qt, Switch SDK)
- UI layer separate from networking/codec.
- Plugin-style front-end integration—each app links to the same core.
- Clear separation of concerns: networking, codec, UI, input management.
- Use of hardware acceleration when available (native decoders, Vulkan via Flatpak).

- Related components (e.g., cluster platform front-ends).
- Protocol layers (discovery, auth, transport, codec).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-End Applications
    subgraph "Front-Ends"
        direction TB
        GUI["GUI (Qt/QML)"]:::frontend
        CLI["CLI"]:::frontend
        Android["Android App"]:::frontend
        SwitchC["Switch Client"]:::frontend
        SteamDeck["Steam Deck Native"]:::frontend
        Setsu["Setsu Demo"]:::frontend
    end

    %% Core Library
    Core["Core Library (lib/)"]:::core

    %% External Services
    subgraph "External Services"
        direction TB
        PSN["PSN Auth Server"]:::external
        HolePunch["Hole-Punch Token Server"]:::external
    end

    %% Internal Dependencies
    subgraph "Dependencies"
        direction TB
        FFmpeg["FFmpeg"]:::dep
        CodecLibs["Opus/SpeexDSP"]:::dep
        Curl["libcurl"]:::dep
        Nanopb["Nanopb"]:::dep
    end

    %% Build & CI/CD
    subgraph "Build & CI/CD"
        direction TB
        CMake["CMake Build System"]:::build
        CI["CI/CD Pipelines"]:::build
        Scripts["Packaging Scripts"]:::build
        Docs["Docs & Test Suite"]:::build
    end

    %% Connections: Front-Ends to Core
    GUI -->|"API calls"| Core
    CLI -->|"API calls"| Core
    Android -->|"API calls"| Core
    SwitchC -->|"API calls"| Core
    SteamDeck -->|"API calls"| Core
    Setsu -->|"API calls"| Core

    %% Core to External Services
    Core ---|"REST/Auth"| PSN
    Core ---|"Discovery/Token"| HolePunch

    %% Core to Dependencies
    Core -->|"Codec Interface"| FFmpeg
    Core -->|"Codec Interface"| CodecLibs
    Core -->|"Networking"| Curl
    Core -->|"Proto Support"| Nanopb

    %% Build & CI/CD interactions
    CMake --> Core
    CI --> Core
    Scripts --> Core
    Docs --> Core

    %% Click Events
    click Core "https://github.com/streetpea/chiaki-ng/tree/main/lib/"
    click GUI "https://github.com/streetpea/chiaki-ng/tree/main/gui/"
    click CLI "https://github.com/streetpea/chiaki-ng/tree/main/cli/"
    click Android "https://github.com/streetpea/chiaki-ng/tree/main/android/app/"
    click SwitchC "https://github.com/streetpea/chiaki-ng/tree/main/switch/"
    click SteamDeck "https://github.com/streetpea/chiaki-ng/tree/main/steamdeck_native/"
    click Setsu "https://github.com/streetpea/chiaki-ng/tree/main/setsu/"
    click HolePunch "https://github.com/streetpea/chiaki-ng/tree/main/scripts/holepunch/"
    click CMake "https://github.com/streetpea/chiaki-ng/blob/main/CMakeLists.txt"
    click CI "https://github.com/streetpea/chiaki-ng/tree/main/.github/workflows/"
    click Scripts "https://github.com/streetpea/chiaki-ng/tree/main/scripts/"
    click Docs "https://github.com/streetpea/chiaki-ng/tree/main/docs/"

    %% Styling
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef frontend fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef dep fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef build fill:#f8d7da,stroke:#721c24,color:#721c24;
```
