# kota-yata/roq-rust architecture

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

- Interactive diagram: https://gitdiagram.com/kota-yata/roq-rust
- Repository: https://github.com/kota-yata/roq-rust

## Overview

##### Project type and purpose
- This is an open-source Rust library (with a small CLI) implementing RTP over QUIC.
- Key capabilities: packetizing/depacketizing RTP, managing QUIC connections, exposing a simple API/command-line tool.

##### File structure
- Top-level files:
- Cargo.toml / Cargo.lock – Rust project metadata & dependencies
- README.md – high-level description
- .gitignore
- src/ directory:
- main.rs – example CLI entrypoint
- roq.rs – public library interface & high-level orchestration
- connection.rs – QUIC transport: handshake, streams, packet send/receive
- rtp.rs – RTP packet framing, parsing, headers
- error.rs – shared error types, result handling

##### README
- Single line: “RTP over QUIC implementation in Rust.”
- Confirms focus on combining RTP (real-time transport protocol) with a QUIC transport layer.

- CLI / Application (main.rs)
- Library core (roq.rs)
- QUIC Connection Manager (connection.rs)
- RTP Packet Processor (rtp.rs)
- Error & Logging module (error.rs)
- Underlying Network / QUIC library (e.g., quinn, tokio-quic)
- External Peer / RTP Endpoint

1. **CLI/Application** → invokes → **roq Library Interface**
2. **roq** → uses → **RTP Packet Processor** to serialize/deserialize RTP packets
3. **roq** → uses → **QUIC Connection Manager** to open QUIC streams and send/receive bytes
4. **QUIC Manager** ↔ communicates over → **Network / QUIC stack** ↔ interacts with → **External Peer**
5. All modules → propagate errors via → **Error module**

c. Architectural patterns & design principles:
- **Modular layering**: clear separation between RTP logic and transport logic
- **Thin public API** in `roq.rs` that composes smaller modules
- **Error handling** centralized in `error.rs` for consistent Result<T, E> across the library

d. Key technologies & libraries:
- Rust (Cargo, Tokio async runtime)
- QUIC implementation (e.g., quinn or quiche under the hood)
- RTP packet format (per RFC 3550)

##### Detailed elements
- main.rs → roq.rs (API call)
- roq.rs → rtp.rs (serialize/deserialize)
- roq.rs → connection.rs (send/receive)
- connection.rs → Network/Peer (QUIC handshake & data)
- Any module → error.rs (error propagation)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI/Application"
        Main["main.rs (CLI/Application)"] 
    end
    subgraph "Core Library Modules"
        PublicAPI["roq.rs (Public API)"]
        RTP["rtp.rs (Packet Processor)"]
        QUIC["connection.rs (QUIC Manager)"]
        Error["error.rs (Error Module)"]
    end
    subgraph "External Systems"
        QUICLib["Underlying QUIC Library / OS"]
        Peer["External RTP Peer"]
    end

    Main -->|"invokes"| PublicAPI
    PublicAPI -->|"serialize/deserialize"| RTP
    PublicAPI -->|"send/receive"| QUIC
    PublicAPI -->|"propagate errors"| Error
    RTP -->|"propagate errors"| Error
    QUIC -->|"propagate errors"| Error
    QUIC -->|"QUIC handshake & data"| QUICLib
    QUICLib -->|"network I/O"| Peer

    click Main "https://github.com/kota-yata/roq-rust/blob/main/src/main.rs"
    click PublicAPI "https://github.com/kota-yata/roq-rust/blob/main/src/roq.rs"
    click RTP "https://github.com/kota-yata/roq-rust/blob/main/src/rtp.rs"
    click QUIC "https://github.com/kota-yata/roq-rust/blob/main/src/connection.rs"
    click Error "https://github.com/kota-yata/roq-rust/blob/main/src/error.rs"

    classDef core fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef external fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef error fill:#FFEBEE,stroke:#C62828,stroke-width:1px
    classDef cli stroke-dasharray: 5 5,stroke:#424242

    class PublicAPI,RTP,QUIC core
    class QUICLib,Peer external
    class Error error
    class Main cli
```
