# roiarthurb/simple.webplatform architecture

> Architecture diagram of the GitHub repository roiarthurb/simple.webplatform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roiarthurb/simple.webplatform
- Repository: https://github.com/roiarthurb/simple.webplatform

## Overview

1. **Repository shape**
   - This is a single TypeScript/React/Vite repository that contains both the **browser UI** and a **Node-side service layer**.
   - The frontend entrypoint is `src/main.tsx`; the backend/service entrypoint is centered around `src/api/index.ts`.
   - The app is built to **monitor and manage GAMA simulations**, multiplayer connections, and device/stream integrations.

2. **User interface layer**
   - Most UI lives under `src/components`, organized by feature rather than by route.
   - Main visible areas include simulation selection/management, stream playback, VR headset handling, websocket status, header/footer/navigation, and language selection.
   - `src/components/SimulationManager`, `StreamPlayerScreen`, `WebSocketManager`, and `VRHeadset` are the key screens/widgets that likely form the operator dashboard.

3. **Global client state and localization**
   - Redux is used for shared UI state (`src/redux/store.ts`, `screenModeSlice.ts`), with a separate `ScreenModeContext` for screen/layout mode handling.
   - Internationalization is built in through `src/i18next/i18n.js` and language packs in `src/languages/*.json` for English, French, Thai, and Vietnamese.
   - This suggests the UI is meant for multilingual operators and different display modes, not a single fixed workflow.

4. **Simulation management boundary**
   - The backend simulation subsystem is under `src/api/simulation`.
   - `GamaConnector.ts`, `Model.ts`, and `ModelManager.ts` indicate a dedicated integration layer for discovering, loading, and controlling GAMA models.
   - The app’s simulation boundary is external: the web platform talks to a running **GAMA Server** rather than hosting the simulation itself.

5. **Multiplayer connection management**
   - `src/api/multiplayer/PlayerManager.ts` is the server-side coordination point for player/session tracking.
   - This is the architecture’s multiplayer boundary: the platform brokers connections between users/clients and the simulation runtime.
   - The README’s emphasis on “monitoring and managing multiplayer connections” matches this subsystem.

6. **Real-time streaming and websocket pipeline**
   - WebSocket-based streaming is a core data path, reflected by `src/components/WebSocketManager` and `src/components/StreamPlayerScreen`.
   - A worker (`src/workers/scrcpyDecoder.ts`) decodes scrcpy video frames, which implies a pipeline from device stream → decode worker → canvas/video rendering in the UI.
   - This is the main low-latency visual path for remote device or VR headset interaction.

7. **Android / device automation integration**
   - `src/api/android/adb` contains `AdbManager`, `DeviceFinder`, and `HeadsetSetup`, so device discovery and setup are handled server-side.
   - `src/api/android/scrcpy/ScrcpyServer.ts` connects the platform to Android screen streaming/control.
   - The `toolkit/` directory contains supporting APKs and the scrcpy server binary, making device enablement part of the deployment package rather than a pure runtime dependency.

8. **Infrastructure services inside the backend**
   - `src/api/infra/StaticServer.ts` serves static content, so the backend is also responsible for hosting the built frontend and related assets.
   - `mDnsService.ts` suggests local-network service discovery, which matters for lab/device environments.
   - `src/api/infra/ups` with `UpsManager.ts` and APC UPS bindings indicates optional power/UPS monitoring as part of the operational stack.

9. **Monitoring subsystem**
   - `src/api/monitoring/MonitorServer.ts` is a distinct server-side component for telemetry/status reporting.
   - In architecture terms, this sits beside simulation control: one path manages experiments, another exposes status/health/monitoring signals.

10. **Content and simulation assets**
   - `learning-packages/demo` contains GAMA demo models, utilities, and GIS-style input data (`.gaml`, `.asc`, shapefiles, etc.).
   - These assets are part of the runtime content model: the platform scans or loads simulation packages from this directory structure, and `.env` can extend that search path.
   - This is a significant data boundary because the system’s behavior depends on external model packages, not just compiled code.

11. **Build, runtime, and delivery**
   - The project is built with **Vite**, **React**, **TypeScript**, **Node.js**, TailwindCSS, and ESLint.
   - Separate Vite configs (`vite.config.ts`, `vite.backend.config.ts`) imply distinct handling for frontend and backend builds.
   - GitHub Actions workflows for CI/release indicate the repo is intended to produce deployable artifacts, likely a web bundle plus supporting server/runtime files.

12. **Primary end-to-end flow**
   - An operator opens the React UI, selects or manages a simulation, and the frontend communicates with backend services over websockets/API.
   - The backend talks to the GAMA server, manages players, and coordinates device/stream services where needed.
   - For VR/device scenarios, Android/ADB/scrcpy components stream video and accept control, while the UI displays the live feed and status.

Main entry points: [`src/api/index.ts`](https://github.com/roiarthurb/simple.webplatform/blob/dev/src/api/index.ts) (API entry), [`src/main.tsx`](https://github.com/roiarthurb/simple.webplatform/blob/dev/src/main.tsx) (App entry), [`src/components`](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components) (UI shell), [`src/components/SimulationManager`](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components/SimulationManager) (Simulation manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser UI"]
  node_src_main["App entry<br/>React boot<br/>[main.tsx]"]
  node_ui_shell["UI shell<br/>layout/components"]
  node_sim_manager_ui["Simulation manager<br/>dashboard screen"]
  node_stream_ui["Stream player<br/>video screen"]
  node_ws_ui["WebSocket manager<br/>realtime client"]
  node_vr_ui["VR headset<br/>device UI"]
  node_screen_mode["Screen mode<br/>client state<br/>[screenModeSlice.ts]"]
  node_i18n["Localization<br/>i18n setup<br/>[i18n.js]"]
  node_languages["Language packs<br/>translations"]
end

subgraph group_backend["Node Services"]
  node_api_entry["API entry<br/>node bootstrap<br/>[index.ts]"]
  node_controller["Core controller<br/>orchestration<br/>[Controller.ts]"]
  node_sim_backend["GAMA bridge<br/>simulation integration"]
  node_multiplayer["Player manager<br/>session coordination<br/>[PlayerManager.ts]"]
  node_device["ADB/Scrcpy<br/>device integration"]
  node_monitoring["Monitoring server<br/>telemetry<br/>[MonitorServer.ts]"]
  node_infra["Infra services<br/>hosting/services"]
  node_worker["Decoder worker<br/>video decode<br/>[scrcpyDecoder.ts]"]
end

subgraph group_content["Simulation Content"]
  node_learning["Demo packages<br/>model assets"]
end

node_src_main -->|"renders"| node_ui_shell
node_src_main -->|"opens"| node_sim_manager_ui
node_src_main -->|"opens"| node_stream_ui
node_src_main -->|"uses"| node_ws_ui
node_src_main -->|"shows"| node_vr_ui
node_ui_shell -->|"reads"| node_screen_mode
node_ui_shell -->|"uses"| node_i18n
node_i18n -->|"loads"| node_languages
node_api_entry -->|"orchestrates"| node_controller
node_api_entry -->|"starts"| node_sim_backend
node_api_entry -->|"starts"| node_multiplayer
node_api_entry -->|"starts"| node_device
node_api_entry -->|"starts"| node_monitoring
node_api_entry -->|"starts"| node_infra
node_sim_manager_ui -->|"controls"| node_sim_backend
node_sim_manager_ui -->|"manages"| node_multiplayer
node_ws_ui -->|"decodes"| node_worker
node_stream_ui -->|"consumes"| node_ws_ui
node_vr_ui -->|"configures"| node_device
node_device -->|"streams"| node_worker
node_sim_backend -->|"loads"| node_learning
node_infra -->|"serves"| node_learning
node_monitoring -->|"reports to"| node_controller

click node_src_main "https://github.com/roiarthurb/simple.webplatform/blob/dev/src/main.tsx"
click node_ui_shell "https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components"
click node_sim_manager_ui "https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components/SimulationManager"
click node_stream_ui "https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components/StreamPlayerScreen"
click node_ws_ui "https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components/WebSocketManager"
click node_vr_ui "https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components/VRHeadset"
click node_screen_mode "https://github.com/roiarthurb/simple.webplatform/blob/dev/src/redux/screenModeSlice.ts"
click node_i18n "https://github.com/roiarthurb/simple.webplatform/blob/dev/src/i18next/i18n.js"
click node_languages "https://github.com/roiarthurb/simple.webplatform/tree/dev/src/languages"
click node_api_entry "https://github.com/roiarthurb/simple.webplatform/blob/dev/src/api/index.ts"
click node_controller "https://github.com/roiarthurb/simple.webplatform/blob/dev/src/api/core/Controller.ts"
click node_sim_backend "https://github.com/roiarthurb/simple.webplatform/tree/dev/src/api/simulation"
click node_multiplayer "https://github.com/roiarthurb/simple.webplatform/blob/dev/src/api/multiplayer/PlayerManager.ts"
click node_device "https://github.com/roiarthurb/simple.webplatform/tree/dev/src/api/android"
click node_monitoring "https://github.com/roiarthurb/simple.webplatform/blob/dev/src/api/monitoring/MonitorServer.ts"
click node_infra "https://github.com/roiarthurb/simple.webplatform/tree/dev/src/api/infra"
click node_worker "https://github.com/roiarthurb/simple.webplatform/blob/dev/src/workers/scrcpyDecoder.ts"
click node_learning "https://github.com/roiarthurb/simple.webplatform/tree/dev/learning-packages/demo"

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_src_main,node_ui_shell,node_sim_manager_ui,node_stream_ui,node_ws_ui,node_vr_ui,node_screen_mode,node_i18n,node_languages toneBlue
class node_api_entry,node_controller,node_sim_backend,node_multiplayer,node_device,node_monitoring,node_infra,node_worker toneAmber
class node_learning toneMint
```

## Components

### Browser UI

React/Vite client side operator dashboard.

- [App entry](https://github.com/roiarthurb/simple.webplatform/blob/dev/src/main.tsx): React boot · Bootstraps the browser application and mounts the UI. · `src/main.tsx`
- [UI shell](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components): layout/components · Top-level header, navigation, footer, and language controls. · `src/components`
- [Simulation manager](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components/SimulationManager): dashboard screen · Main operator surface for selecting and controlling simulations. · `src/components/SimulationManager`
- [Stream player](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components/StreamPlayerScreen): video screen · Displays remote device or simulation stream playback. · `src/components/StreamPlayerScreen`
- [WebSocket manager](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components/WebSocketManager): realtime client · Manages websocket status and live video/control transport in the UI. · `src/components/WebSocketManager`
- [VR headset](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/components/VRHeadset): device UI · Headset-specific operator controls and status. · `src/components/VRHeadset`
- [Screen mode](https://github.com/roiarthurb/simple.webplatform/blob/dev/src/redux/screenModeSlice.ts): client state · Shared layout and display-mode state. · `src/redux/screenModeSlice.ts`
- [Localization](https://github.com/roiarthurb/simple.webplatform/blob/dev/src/i18next/i18n.js): i18n setup · Initializes language handling for the multilingual UI. · `src/i18next/i18n.js`
- [Language packs](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/languages): translations · UI translations for supported operator languages. · `src/languages`

### Node Services

Server-side APIs and operational integrations.

- [API entry](https://github.com/roiarthurb/simple.webplatform/blob/dev/src/api/index.ts): node bootstrap · Starts the backend service layer and wires runtime subsystems. · `src/api/index.ts`
- [Core controller](https://github.com/roiarthurb/simple.webplatform/blob/dev/src/api/core/Controller.ts): orchestration · Central backend coordination and shared constants. · `src/api/core/Controller.ts`
- [GAMA bridge](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/api/simulation): simulation integration · Connects the platform to external GAMA Server models and control. · `src/api/simulation`
- [Player manager](https://github.com/roiarthurb/simple.webplatform/blob/dev/src/api/multiplayer/PlayerManager.ts): session coordination · Tracks multiplayer players and connection state. · `src/api/multiplayer/PlayerManager.ts`
- [ADB/Scrcpy](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/api/android): device integration · Discovers Android devices, prepares headsets, and starts scrcpy streaming. · `src/api/android`
- [Monitoring server](https://github.com/roiarthurb/simple.webplatform/blob/dev/src/api/monitoring/MonitorServer.ts): telemetry · Exposes health and operational status reporting. · `src/api/monitoring/MonitorServer.ts`
- [Infra services](https://github.com/roiarthurb/simple.webplatform/tree/dev/src/api/infra): hosting/services · Static hosting, mDNS discovery, and UPS support. · `src/api/infra`
- [Decoder worker](https://github.com/roiarthurb/simple.webplatform/blob/dev/src/workers/scrcpyDecoder.ts): video decode · Decodes scrcpy frames off the main thread. · `src/workers/scrcpyDecoder.ts`

### Simulation Content

External model packages and demo assets loaded at runtime.

- [Demo packages](https://github.com/roiarthurb/simple.webplatform/tree/dev/learning-packages/demo): model assets · GAMA demo models, GIS inputs, and runtime package data. · `learning-packages/demo`

## Connections

- App entry → UI shell: renders · Main entry mounts the operator interface.
- App entry → Simulation manager: opens · Primary dashboard area for simulation control.
- App entry → Stream player: opens · Shows live stream playback views.
- App entry → WebSocket manager: uses · Connects the app to realtime status and transport.
- App entry → VR headset: shows · Provides VR/headset-specific controls.
- UI shell → Screen mode: reads · Layout changes follow shared screen mode state.
- UI shell → Localization: uses · Shell and controls are localized.
- Localization → Language packs: loads · Language packs provide translation strings.
- API entry → Core controller: orchestrates · Backend entry wires the core runtime controller.
- API entry → GAMA bridge: starts · Starts the simulation integration layer.
- API entry → Player manager: starts · Starts player/session coordination.
- API entry → ADB/Scrcpy: starts · Starts Android and scrcpy integrations.
- API entry → Monitoring server: starts · Starts monitoring and status services.
- API entry → Infra services: starts · Hosts static assets and local-network services.
- Simulation manager → GAMA bridge: controls · Simulation actions are sent to the GAMA bridge.
- Simulation manager → Player manager: manages · Operator dashboard reflects player/session state.
- WebSocket manager → Decoder worker: decodes · Stream frames are decoded in a worker.
- Stream player → WebSocket manager: consumes · Playback view depends on websocket transport.
- VR headset → ADB/Scrcpy: configures · Headset setup is handled by device services.
- ADB/Scrcpy → Decoder worker: streams · Scrcpy video frames feed the decoder pipeline.
- GAMA bridge → Demo packages: loads · GAMA bridge discovers and loads model packages.
- Infra services → Demo packages: serves · Static hosting can expose bundled content and assets.
- Monitoring server → Core controller: reports to · Monitoring exposes operational state from the core runtime.
