# vu-ase/rover architecture

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

- Interactive diagram: https://gitdiagram.com/vu-ase/rover
- Repository: https://github.com/vu-ase/rover

## Overview

##### Project type and purpose
- This is a distributed, full-stack “Rover Control” system comprised of three coordinated pieces:
- roverd – a Rust-based daemon running on the Rover hardware that schedules and executes pipelines and services via a REST API (per the OpenAPI spec in `spec/api`).
- roverctl – a Go CLI tool that talks to `roverd`’s REST API and also runs a local proxy (WebRTC/WebSocket) to forward browser traffic.
- roverctl-web – a SvelteKit web frontend that uses a generated TypeScript client against the OpenAPI spec, connecting through the `roverctl` proxy for live control and monitoring.

##### File structure
- Top-level: three component roots (`roverd/`, `roverctl/`, `roverctl-web/`), a shared `spec/` folder for API and configuration schemas, `manage/` scripts for batch operations, and `.github/` CI.
- Each of the three components has its own Dockerfile and devcontainer for isolated development.
- OpenAPI codegen artifacts under both `roverd/openapi` and `roverctl-web/src/lib/openapi`.

##### Relationships & data flows
- User types CLI commands → `roverctl` → HTTP → `roverd`
- Browser connects to `roverctl`’s WebRTC proxy → WebSocket → `roverctl` → HTTP → `roverd`
- OpenAPI spec (`spec/api/schema.yaml`) is the single source of truth → codegen → `roverd/openapi` & `roverctl-web/src/lib/openapi`

##### Architectural patterns & design principles
- **Separation of Concerns**: Edge service (roverd), local control/proxy (roverctl), browser UI (roverctl-web)
- **Contract-First**: OpenAPI-driven API design and client generation
- **Proxy Pattern**: roverctl serves as an HTTP↔WebRTC bridge for secure, debuggable remote access
- **State Machine**: roverd’s internal pipeline scheduler follows a well-defined state machine

##### Technologies & frameworks
- roverd: Rust, Tokio/async HTTP framework, OpenAPI codegen, state machine module
- roverctl: Go, Cobra CLI, net/http, Pion WebRTC or similar
- roverctl-web: SvelteKit, Vite, TypeScript, OpenAPI generator, Tailwind CSS

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Shared Spec
    spec["OpenAPI Spec\n(spec/api/schema.yaml)"]:::spec

    %% Edge Layer
    subgraph "Edge (Rover Hardware)"
        direction TB
        roverdSrc["Roverd Source\n(roverd/roverd/src)"]:::rust
        httpServer["HTTP Server\n(roverd/openapi/src/server & roverd/roverd/src/apis)"]:::rust
        stateMachine["StateMachine Engine\n(state.rs)"]:::rust
        scheduler["Service Scheduler\n(process.rs & daemons.rs)"]:::rust
    end

    %% Local Control Layer
    subgraph "Local Control (roverctl)"
        direction TB
        cliCmd["CLI Commands\n(src/commands)"]:::go
        proxyCore["Proxy Core\n(src/proxy/proxy.go)"]:::go
        subgraph "Proxy Components"
            direction TB
            proxyEvents["Events\n(src/proxy/events)"]:::go
            httpServerProxy["HTTP Server\n(src/proxy/httpserver/init.go)"]:::go
            peerConnection["PeerConnection\n(src/proxy/peerconnection)"]:::go
        end
    end

    %% Client Layer
    subgraph "Client (Browser & Web UI)"
        direction TB
        browser["Browser UI"]:::js
        webServer["Web Server\n(Vite/Node)"]:::js
        webRoutes["Routes & Components\n(src/routes & src/components)"]:::js
        webOpenapi["OpenAPI Client\n(src/lib/openapi)"]:::js
        webStore["Stores & Config\n(src/lib/store)"]:::js
        staticAssets["Static Assets\n(static)"]:::js
        viteConfig["Vite Config\n(vite.config.ts)"]:::js
    end

    %% Connections
    spec -->|"codegen"| httpServer
    spec -->|"codegen"| webOpenapi

    cliCmd -->|"HTTP"| httpServer
    browser -->|"WebSocket/WebRTC"| proxyCore
    proxyCore -->|"HTTP"| httpServer

    browser --> webServer
    webServer --> webRoutes
    webRoutes --> webOpenapi
    webOpenapi --> httpServer

    %% Click Events
    click spec "https://github.com/vu-ase/rover/blob/main/spec/api/schema.yaml"

    click roverdSrc "https://github.com/vu-ase/rover/tree/main/roverd/roverd/src"
    click httpServer "https://github.com/vu-ase/rover/tree/main/roverd/openapi/src/server"
    click httpServer "https://github.com/vu-ase/rover/tree/main/roverd/roverd/src/apis"
    click stateMachine "https://github.com/vu-ase/rover/blob/main/roverd/roverd/src/app/state.rs"
    click stateMachine "https://github.com/vu-ase/rover/blob/main/docs/02-roverd/StateMachine.drawio"
    click scheduler "https://github.com/vu-ase/rover/blob/main/roverd/roverd/src/app/process.rs"
    click scheduler "https://github.com/vu-ase/rover/blob/main/roverd/roverd/src/app/daemons.rs"

    click cliCmd "https://github.com/vu-ase/rover/tree/main/roverctl/src/commands"
    click proxyCore "https://github.com/vu-ase/rover/blob/main/roverctl/src/proxy/proxy.go"
    click proxyEvents "https://github.com/vu-ase/rover/tree/main/roverctl/src/proxy/events"
    click httpServerProxy "https://github.com/vu-ase/rover/blob/main/roverctl/src/proxy/httpserver/init.go"
    click peerConnection "https://github.com/vu-ase/rover/tree/main/roverctl/src/proxy/peerconnection"

    click webRoutes "https://github.com/vu-ase/rover/tree/main/roverctl-web/src/routes"
    click webRoutes "https://github.com/vu-ase/rover/tree/main/roverctl-web/src/components"
    click webOpenapi "https://github.com/vu-ase/rover/tree/main/roverctl-web/src/lib/openapi"
    click webStore "https://github.com/vu-ase/rover/tree/main/roverctl-web/src/lib/store"
    click staticAssets "https://github.com/vu-ase/rover/tree/main/roverctl-web/static"
    click viteConfig "https://github.com/vu-ase/rover/blob/main/roverctl-web/vite.config.ts"

    %% Styles
    classDef rust fill:#fdd,stroke:#b55;
    classDef go fill:#dfd,stroke:#5b5;
    classDef js fill:#ddf,stroke:#55b;
    classDef spec fill:#ffd,stroke:#bb5;
```
