# koalbymqp/zaraos-driverstation architecture

> Architecture diagram of the GitHub repository koalbymqp/zaraos-driverstation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/koalbymqp/zaraos-driverstation
- Repository: https://github.com/koalbymqp/zaraos-driverstation

## Overview

ZaraOS Driver Station is a browser-based control interface for connecting to robots, managing running applications, and viewing logs. The principal workflow is sign in, connect or pair with a robot, browse releases and start or stop instances, then inspect their logs or open a console. The graph also preserves the documented local-development and BLE connection routes, authentication, and Azure token proxy. Backend implementation is absent from the supplied tree, so robot APIs are shown as external; edges reflect only the supplied excerpts and README.

Main entry points: [`driver-station/app/layout.tsx`](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/layout.tsx) (Application providers), [`driver-station/app/apps/page.tsx`](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/apps/page.tsx) (App catalog), [`driver-station/contexts/ConnectionContext.tsx`](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/contexts/ConnectionContext.tsx) (Connection state), [`driver-station/app/page.tsx`](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/page.tsx) (Home dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and shell"]
  node_signin["Sign in<br/>[page.tsx]"]
  node_home["Home dashboard<br/>[page.tsx]"]
  node_header["Navigation header<br/>[Header.tsx]"]
end

subgraph group_connection["Robot connection"]
  node_ble["BLE IP discovery<br/>[ble-get-ip.ts]"]
  node_bleids["BLE identifiers<br/>[ble-uuid.ts]"]
  node_connectionstate["Connection state"]
  node_connectui["Connect controls<br/>[IpConnectModal.tsx]"]
  node_health["Connection health"]
  node_status["Connection status"]
end

subgraph group_operations["Robot operations"]
  node_apps["App catalog<br/>[page.tsx]"]
  node_logs["Logs page<br/>[page.tsx]"]
  node_console["Robot console<br/>[page.tsx]"]
  node_robotapi["Robot API client<br/>[robot-api.ts]"]
  node_logsviewer["Log viewer<br/>[LogViewer.tsx]"]
  node_logstream["Log streaming<br/>[log-stream.ts]"]
  node_ssh["SSH terminal<br/>[SSHTerminal.tsx]"]
  node_archiver["Log archiver<br/>[log-archiver.ts]"]
end

subgraph group_support["Shared support"]
  node_api["Backend API client<br/>[api.ts]"]
  node_auth["Authentication state<br/>[AuthContext.tsx]"]
  node_msal["MSAL configuration<br/>[msalConfig.ts]"]
  node_msalwrap["MSAL provider<br/>[MsalWrapper.tsx]"]
  node_azureproxy["Azure token proxy<br/>[route.ts]"]
  node_projects["Project state<br/>[ProjectContext.tsx]"]
  node_theme["Theme preferences<br/>[ThemeContext.tsx]"]
  node_layout["Application providers<br/>[layout.tsx]"]
end

node_operator(("Operator"))
node_robot["ZaraOS robot API"]
node_catalogapi["Release metadata API"]
node_azure["Microsoft identity"]

node_operator -->|"starts sign-in"| node_signin
node_signin -.->|"requests identity token"| node_azure
node_operator -->|"connects robot"| node_connectui
node_connectui -.->|"discovers IP"| node_ble
node_ble -->|"uses UUIDs"| node_bleids
node_connectui -.->|"sets connection"| node_connectionstate
node_connectionstate -->|"connects over HTTP"| node_robot
node_health -.->|"monitors connection"| node_connectionstate
node_home -->|"renders status"| node_status
node_home -->|"renders header"| node_header
node_home -->|"shows project status"| node_projects
node_operator -->|"browses and manages apps"| node_apps
node_apps -->|"loads releases"| node_api
node_apps -->|"manages instances"| node_robotapi
node_robotapi -.->|"sends robot requests"| node_robot
node_apps -.->|"updates active projects"| node_projects
node_operator -->|"opens logs"| node_logs
node_logs -->|"fetches instances"| node_robotapi
node_logs -->|"selects instance"| node_logsviewer
node_logsviewer -.->|"streams logs"| node_logstream
node_logstream -.->|"reads robot logs"| node_robot
node_operator -->|"opens console"| node_console
node_console -.->|"opens terminal"| node_ssh
node_ssh -.->|"sends terminal commands"| node_robot
node_operator -.->|"requests token"| node_azureproxy
node_azureproxy -->|"forwards token request"| node_azure
node_archiver -.->|"archives logs"| node_robot
node_layout -->|"wraps application"| node_msalwrap
node_layout -->|"provides auth state"| node_auth
node_layout -->|"provides connection state"| node_connectionstate
node_layout -->|"provides project state"| node_projects
node_layout -->|"provides theme"| node_theme
node_msalwrap -.->|"uses configuration"| node_msal

click node_signin "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/authenticate/page.tsx"
click node_home "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/page.tsx"
click node_apps "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/apps/page.tsx"
click node_logs "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/logs/page.tsx"
click node_console "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/console/page.tsx"
click node_ble "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/ble-get-ip.ts"
click node_bleids "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/ble-uuid.ts"
click node_connectionstate "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/contexts/ConnectionContext.tsx"
click node_connectui "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/IpConnectModal.tsx"
click node_health "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/ConnectionHealthMonitor.tsx"
click node_status "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/ConnectionStatusWidget.tsx"
click node_robotapi "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/robot-api.ts"
click node_logsviewer "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/LogViewer.tsx"
click node_logstream "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/log-stream.ts"
click node_ssh "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/SSHTerminal.tsx"
click node_api "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/api.ts"
click node_auth "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/contexts/AuthContext.tsx"
click node_msal "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/msalConfig.ts"
click node_msalwrap "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/MsalWrapper.tsx"
click node_azureproxy "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/api/azure-token-proxy/route.ts"
click node_projects "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/contexts/ProjectContext.tsx"
click node_theme "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/contexts/ThemeContext.tsx"
click node_archiver "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/workflows/log-archiver.ts"
click node_layout "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/layout.tsx"
click node_header "https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/Header.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_signin,node_home,node_header toneBlue
class node_ble,node_bleids,node_connectionstate,node_connectui,node_health,node_status toneAmber
class node_apps,node_logs,node_console,node_robotapi,node_logsviewer,node_logstream,node_ssh,node_archiver,node_robot,node_catalogapi toneMint
class node_api,node_auth,node_msal,node_msalwrap,node_azureproxy,node_projects,node_theme,node_layout toneRose
class node_operator,node_azure toneIndigo
```

## Components

### Access and shell

- [Sign in](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/authenticate/page.tsx): `driver-station/app/authenticate/page.tsx`
- [Home dashboard](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/page.tsx): `driver-station/app/page.tsx`
- [Navigation header](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/Header.tsx): `driver-station/components/Header.tsx`

### Robot connection

- [BLE IP discovery](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/ble-get-ip.ts): `driver-station/lib/ble-get-ip.ts`
- [BLE identifiers](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/ble-uuid.ts): `driver-station/lib/ble-uuid.ts`
- [Connection state](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/contexts/ConnectionContext.tsx): `driver-station/contexts/ConnectionContext.tsx`
- [Connect controls](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/IpConnectModal.tsx): `driver-station/components/IpConnectModal.tsx`
- [Connection health](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/ConnectionHealthMonitor.tsx): `driver-station/components/ConnectionHealthMonitor.tsx`
- [Connection status](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/ConnectionStatusWidget.tsx): `driver-station/components/ConnectionStatusWidget.tsx`

### Robot operations

- [App catalog](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/apps/page.tsx): `driver-station/app/apps/page.tsx`
- [Logs page](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/logs/page.tsx): `driver-station/app/logs/page.tsx`
- [Robot console](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/console/page.tsx): `driver-station/app/console/page.tsx`
- [Robot API client](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/robot-api.ts): `driver-station/lib/robot-api.ts`
- [Log viewer](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/LogViewer.tsx): `driver-station/components/LogViewer.tsx`
- [Log streaming](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/log-stream.ts): `driver-station/lib/log-stream.ts`
- [SSH terminal](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/SSHTerminal.tsx): `driver-station/components/SSHTerminal.tsx`
- [Log archiver](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/workflows/log-archiver.ts): `driver-station/workflows/log-archiver.ts`

### Shared support

- [Backend API client](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/api.ts): `driver-station/lib/api.ts`
- [Authentication state](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/contexts/AuthContext.tsx): `driver-station/contexts/AuthContext.tsx`
- [MSAL configuration](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/lib/msalConfig.ts): `driver-station/lib/msalConfig.ts`
- [MSAL provider](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/components/MsalWrapper.tsx): `driver-station/components/MsalWrapper.tsx`
- [Azure token proxy](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/api/azure-token-proxy/route.ts): `driver-station/app/api/azure-token-proxy/route.ts`
- [Project state](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/contexts/ProjectContext.tsx): `driver-station/contexts/ProjectContext.tsx`
- [Theme preferences](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/contexts/ThemeContext.tsx): `driver-station/contexts/ThemeContext.tsx`
- [Application providers](https://github.com/koalbymqp/zaraos-driverstation/blob/main/driver-station/app/layout.tsx): `driver-station/app/layout.tsx`

### Other components

- **Operator**
- **ZaraOS robot API**
- **Release metadata API**
- **Microsoft identity**

## Connections

- Operator → Sign in: starts sign-in (evidence: `driver-station/app/authenticate/page.tsx`)
- Sign in → Microsoft identity: requests identity token
- Operator → Connect controls: connects robot
- Connect controls → BLE IP discovery: discovers IP
- BLE IP discovery → BLE identifiers: uses UUIDs (evidence: `driver-station/lib/ble-get-ip.ts`)
- Connect controls → Connection state: sets connection
- Connection state → ZaraOS robot API: connects over HTTP
- Connection health → Connection state: monitors connection
- Home dashboard → Connection status: renders status (evidence: `driver-station/app/page.tsx`)
- Home dashboard → Navigation header: renders header (evidence: `driver-station/app/page.tsx`)
- Home dashboard → Project state: shows project status (evidence: `driver-station/app/page.tsx`)
- Operator → App catalog: browses and manages apps
- App catalog → Backend API client: loads releases (evidence: `driver-station/app/apps/page.tsx`)
- App catalog → Robot API client: manages instances (evidence: `driver-station/app/apps/page.tsx`)
- Robot API client → ZaraOS robot API: sends robot requests
- App catalog → Project state: updates active projects
- Operator → Logs page: opens logs
- Logs page → Robot API client: fetches instances (evidence: `driver-station/app/logs/page.tsx`)
- Logs page → Log viewer: selects instance (evidence: `driver-station/app/logs/page.tsx`)
- Log viewer → Log streaming: streams logs
- Log streaming → ZaraOS robot API: reads robot logs
- Operator → Robot console: opens console
- Robot console → SSH terminal: opens terminal
- SSH terminal → ZaraOS robot API: sends terminal commands
- Operator → Azure token proxy: requests token
- Azure token proxy → Microsoft identity: forwards token request (evidence: `driver-station/app/api/azure-token-proxy/route.ts`)
- Log archiver → ZaraOS robot API: archives logs
- Application providers → MSAL provider: wraps application (evidence: `driver-station/app/layout.tsx`)
- Application providers → Authentication state: provides auth state (evidence: `driver-station/app/layout.tsx`)
- Application providers → Connection state: provides connection state (evidence: `driver-station/app/layout.tsx`)
- Application providers → Project state: provides project state (evidence: `driver-station/app/layout.tsx`)
- Application providers → Theme preferences: provides theme (evidence: `driver-station/app/layout.tsx`)
- MSAL provider → MSAL configuration: uses configuration
