# nestrilabs/nestri architecture

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

- Interactive diagram: https://gitdiagram.com/nestrilabs/nestri
- Repository: https://github.com/nestrilabs/nestri

## Overview

##### Main System Components

a) Client Layer:
- Frontend applications (Qwik-based web interface)
- User interfaces for game management and streaming
- Input handling systems (keyboard, mouse, controller support)

b) Infrastructure Layer:
- Cloudflare Services (Workers, Pages)
- AWS Route53 for DNS
- Supabase for database
- Media-Over-Quic (MOQ) streaming protocol

c) Core Gaming Layer:
- CrosVM with Virtio-GPU Venus/Virgl support
- Game containers and virtualization
- GPU passthrough system
- Streaming encoders/decoders

##### Component Relationships

a) User Flow:
**Client Browser -> Cloudflare Pages -> API Workers -> Gaming Backend**

b) Streaming Flow:
**Game Instance -> MOQ Protocol -> Relay Server -> Client Browser**

c) Data Flow:
**User Actions -> Input Handler -> Game Instance -> Video/Audio Stream -> Client**

##### Key Architectural Elements

Specific components:

a) Frontend Services:
- Website (apps/www)
- Documentation (apps/docs)
- UI Components (packages/ui)

b) Backend Services:
- Relay Server (packages/relay)
- Master Server (packages/master)
- API Server (packages/api)

c) Core Components:
- MOQ Implementation (packages/moq)
- Input Handler (packages/input)
- Server Runtime (packages/server)

##### Specific Implementation Details

Technical implementations:

a) Container Architecture:
**Docker Container**
- CrosVM
- Game Instance
- Virtio-GPU Support
- GPU Passthrough

b) Streaming Pipeline:
**Game Output -> Video Encoding -> MOQ Protocol -> Relay -> Client Decoder**

##### Additional Elements

Features:
- Family sharing system
- Multiplayer session management
- Stream broadcasting to YouTube/Twitch
- Save state management

##### Integration Points

Connections:
- Game store integrations (Steam, Epic, GOG)
- Streaming platform integrations
- Authentication system
- API endpoints

This architecture should emphasize Nestri's position as a self-hosted solution while showing how it achieves its goal of providing a comprehensive cloud gaming platform with social features.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef infrastructure fill:#2ecc71,stroke:#27ae60,color:white
    classDef gaming fill:#e67e22,stroke:#d35400,color:white
    classDef streaming fill:#9b59b6,stroke:#8e44ad,color:white
    classDef database fill:#34495e,stroke:#2c3e50,color:white
    
    %% Client Layer
    subgraph ClientLayer["Client Layer"]
        WebUI["Web Interface"]:::frontend
        Docs["Documentation Site"]:::frontend
        UIComp["UI Components"]:::frontend
        InputSystem["Input Handler"]:::frontend
        Cache["Frontend Cache"]:::frontend
    end

    %% Infrastructure Layer
    subgraph InfraLayer["Infrastructure Layer"]
        CF["Cloudflare Services"]:::infrastructure
        Route53["AWS Route53"]:::infrastructure
        Supabase[(Supabase DB)]:::database
        CertMgmt["Certificate Management"]:::infrastructure
        InfraConfig["Infrastructure Config"]:::infrastructure
    end

    %% Gaming Layer
    subgraph GamingLayer["Gaming Layer"]
        subgraph Virtualization["Virtualization"]
            CrosVM["CrosVM"]:::gaming
            GPUPass["GPU Passthrough"]:::gaming
            GameCont["Game Container System"]:::gaming
        end
        
        subgraph ServerComponents["Server Components"]
            ServerRT["Server Runtime"]:::gaming
            MasterSrv["Master Server"]:::gaming
            APISrv["API Server"]:::gaming
        end
    end

    %% Streaming Layer
    subgraph StreamingLayer["Streaming Layer"]
        MOQ["MOQ Protocol"]:::streaming
        RelaySrv["Relay Server"]:::streaming
        Encoder["Video Encoder"]:::streaming
    end

    %% Relationships
    WebUI --> CF
    CF --> APISrv
    InputSystem --> RelaySrv
    RelaySrv --> MOQ
    MOQ --> CrosVM
    ServerRT --> GPUPass
    MasterSrv --> GameCont
    APISrv --> Supabase
    Route53 --> CF
    CertMgmt --> RelaySrv

    %% Click Events
    click WebUI "https://github.com/nestrilabs/nestri/tree/main/apps/www"
    click Docs "https://github.com/nestrilabs/nestri/tree/main/apps/docs"
    click UIComp "https://github.com/nestrilabs/nestri/tree/main/packages/ui"
    click InputSystem "https://github.com/nestrilabs/nestri/tree/main/packages/input"
    click MOQ "https://github.com/nestrilabs/nestri/tree/main/packages/moq"
    click ServerRT "https://github.com/nestrilabs/nestri/tree/main/packages/server"
    click RelaySrv "https://github.com/nestrilabs/nestri/tree/main/packages/relay"
    click MasterSrv "https://github.com/nestrilabs/nestri/tree/main/packages/master"
    click APISrv "https://github.com/nestrilabs/nestri/tree/main/packages/api"
    click InfraConfig "https://github.com/nestrilabs/nestri/tree/main/infra"
    click GameCont "https://github.com/nestrilabs/nestri/tree/main/packages/docker-to-rootfs"
    click GPUPass "https://github.com/nestrilabs/nestri/blob/main/packages/server/src/gpu.rs"
    click Cache "https://github.com/nestrilabs/nestri/tree/main/packages/cache"
    click CertMgmt "https://github.com/nestrilabs/nestri/tree/main/packages/certs"

    %% Legend
    subgraph Legend
        Frontend["Frontend Component"]:::frontend
        Infra["Infrastructure Component"]:::infrastructure
        Gaming["Gaming Component"]:::gaming
        Stream["Streaming Component"]:::streaming
        DB["Database"]:::database
    end
```
