# project-simple/simple.webplatform architecture

> Architecture diagram of the GitHub repository project-simple/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/project-simple/simple.webplatform
- Repository: https://github.com/project-simple/simple.webplatform

## Overview

1. **Overall shape**
   - This repository is a **React + TypeScript + Vite** single-page web platform.
   - It is not just a UI: it also contains a substantial **integration/service layer** under `src/api` for connecting to external systems such as **GAMA simulation servers**, **Android devices**, and **real-time streaming/monitoring services**.

2. **Primary purpose**
   - The app’s main job is to **monitor and manage GAMA-based simulations**, especially multiplayer or VR-oriented scenarios.
   - The README and file tree show three recurring domains:
     - **Simulation selection/management**
     - **Player/multiplayer coordination**
     - **Remote device/video streaming for interactive sessions**

3. **Frontend composition**
   - The UI is organized into reusable components under `src/components`.
   - Notable screens/features include:
     - `SelectorSimulations` for choosing available experiments
     - `SimulationManager` for controlling running simulations and players
     - `StreamPlayerScreen` and `WebSocketManager` for viewing/controlling live streams
     - `VRHeadset` for VR-specific interaction
     - Common shell components like `Header`, `Footer`, `Navigation`, `LanguageSelector`, and `Button`
   - This suggests a **dashboard-style interface** rather than a content site.

4. **Application state and cross-cutting UI concerns**
   - Global state is managed with **Redux** (`src/redux/store.ts`, `screenModeSlice.ts`).
   - `ScreenModeContext` indicates an additional UI-level context for display mode or layout switching.
   - Internationalization is built in via **i18next**, with translated strings in `src/languages` for English, French, Thai, and Vietnamese.

5. **Service / integration layer**
   - `src/api` is the architectural boundary where the browser-facing UI meets external systems.
   - It is split into clear subdomains:
     - `core`: shared controller/constants
     - `simulation`: GAMA connectivity and simulation model management
     - `multiplayer`: player/session coordination
     - `monitoring`: server-side monitoring endpoints
     - `android`: ADB and scrcpy control
     - `infra`: network discovery and infrastructure helpers

6. **GAMA simulation integration**
   - The `simulation` area (`GamaConnector`, `Model`, `ModelManager`) is the central bridge to the GAMA platform.
   - The app likely discovers, loads, and manages simulation experiments from one or more package roots, driven by `.env` configuration such as `EXTRA_LEARNING_PACKAGE_PATH`.
   - The `learning-packages/demo` tree contains bundled GAMA models, utilities, and sample assets, which appear to serve as a local experiment library for the platform.

7. **Multiplayer and player management flow**
   - `src/api/multiplayer/PlayerManager.ts` suggests that the platform tracks connected players, their assignment to sessions, and possibly their screen/control state.
   - UI components like `SimulationManagerPlayer` and `SimulationManagerButtons` likely reflect this backend state to the operator.
   - The architecture implies a **control-plane flow**: the web UI manages players and sessions, while the actual simulation runs elsewhere in GAMA.

8. **Streaming and remote device boundary**
   - `src/api/android/adb` and `src/api/android/scrcpy` integrate with Android devices and the `scrcpy` server binary stored in `toolkit/`.
   - This indicates the platform can mirror or control a physical device’s display, probably for mobile/VR client scenarios.
   - UI pieces such as `StreamPlayerScreen`, `VideoStreamManager`, and `PlayerScreenCanvas` consume this stream and render it in the browser.

9. **Network discovery and server reachability**
   - `src/api/infra/mDnsService.ts` shows that the platform can use **mDNS** for discovery, likely to find local services/devices automatically.
   - The README also references configurable host/port values like `GAMA_WS_PORT` and `GAMA_IP_ADRESS`, so the app is designed to connect to external services over the local network rather than embedding them.

10. **Monitoring subsystem**
   - `src/api/monitoring/MonitorServer.ts` implies a dedicated monitoring endpoint or process wrapper for observing system/simulation status.
   - In the UI, this likely feeds dashboards, connection state, or live telemetry rather than user-generated content.

11. **Simulation content and assets**
   - The `learning-packages/demo` folder is a major data asset boundary.
   - It contains:
     - GAMA model files (`.gaml`)
     - GIS-like input data (`.asc`, `.shp`, `.dbf`, `.prj`, etc.)
     - demo settings and splash screen assets
   - Architecturally, this is the repository’s **sample experiment catalog**, not app logic.

12. **Entry points and build/runtime**
   - `src/main.tsx`, `index.html`, and `vite.config.ts` define the client application entry and development/build pipeline.
   - Styling is handled with **TailwindCSS** and `postcss`, while ESLint and TypeScript configs enforce code quality.
   - `package.json` likely drives a local dev server on port `8000` as described in the README.

13. **Key external dependencies and boundaries**
   - The two most important external systems are:
     - **GAMA Server** for simulation execution and control
     - **Android/scrcpy/ADB** for device mirroring and interaction
   - The architecture is therefore a **browser-based orchestration layer** sitting between an operator and several runtime systems, rather than a standalone simulation engine.

14. **How to diagram it**
   - A good architecture diagram would show:
     - Browser UI / React app at the center
     - A separate `src/api` integration layer beneath it
     - Connections from that layer to GAMA Server, Android/ADB/scrcpy, and local network discovery/monitoring
     - A data/content sidecar for `learning-packages/demo` experiment assets
   - The main data flow is: **configuration + discovered services → API layer → UI state/components → operator actions back to services**.

Main entry points: [`src/api/index.ts`](https://github.com/project-simple/simple.webplatform/blob/main/src/api/index.ts) (API facade), [`src/main.tsx`](https://github.com/project-simple/simple.webplatform/blob/main/src/main.tsx) (App entry), [`src/redux/store.ts`](https://github.com/project-simple/simple.webplatform/blob/main/src/redux/store.ts) (Redux store), [`src/api/android/adb/AdbManager.ts`](https://github.com/project-simple/simple.webplatform/blob/main/src/api/android/adb/AdbManager.ts) (Android bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend app"]
  node_main["App entry<br/>React/Vite entry<br/>[main.tsx]"]
  node_header["Shell header<br/>UI shell<br/>[Header.tsx]"]
  node_nav["Navigation<br/>UI shell<br/>[Navigation.tsx]"]
  node_lang["Language picker<br/>i18n UI"]
  node_selector["Simulation picker<br/>screen"]
  node_manager["Simulation manager<br/>screen"]
  node_stream["Stream screen"]
  node_wsmgr["Stream bridge<br/>stream UI"]
  node_vr["VR headset<br/>VR UI<br/>[VRHeadset.tsx]"]
  node_screenmode["Screen mode<br/>context/store"]
  node_redux["Redux store<br/>state<br/>[store.ts]"]
  node_i18n["Translations<br/>i18n<br/>[i18n.js]"]
end

subgraph group_api["Integration layer"]
  node_apiindex["API facade<br/>integration entry<br/>[index.ts]"]
  node_core["Core control<br/>shared API<br/>[Controller.ts]"]
  node_gama["GAMA connector<br/>simulation API<br/>[GamaConnector.ts]"]
  node_models["Model manager<br/>simulation API<br/>[ModelManager.ts]"]
  node_players["Player manager<br/>multiplayer API<br/>[PlayerManager.ts]"]
  node_android["Android bridge<br/>device API<br/>[AdbManager.ts]"]
  node_scrcpy["Scrcpy server<br/>device API<br/>[ScrcpyServer.ts]"]
  node_mdns["mDNS discovery<br/>infra API<br/>[mDnsService.ts]"]
  node_monitor["Monitor server<br/>monitoring API<br/>[MonitorServer.ts]"]
end

subgraph group_content["Experiment content"]
  node_demo["Demo library<br/>GAMA content<br/>[settings.json]"]
end

subgraph group_runtime["External runtimes"]
  node_gamaext[("GAMA server<br/>external runtime")]
  node_androidext[("Android device<br/>external runtime")]
  node_scrcpyext[("scrcpy runtime<br/>external runtime")]
end

node_main -->|"renders"| node_header
node_main -->|"routes to"| node_selector
node_main -->|"routes to"| node_manager
node_main -->|"routes to"| node_stream
node_header -->|"contains"| node_nav
node_header -->|"contains"| node_lang
node_selector -->|"reads state"| node_redux
node_manager -->|"reads state"| node_redux
node_stream -->|"uses"| node_wsmgr
node_wsmgr -->|"uses"| node_screenmode
node_redux -->|"includes"| node_screenmode
node_redux -->|"coordinates"| node_i18n
node_apiindex -->|"bundles"| node_core
node_apiindex -->|"bundles"| node_gama
node_apiindex -->|"bundles"| node_players
node_apiindex -->|"bundles"| node_android
node_apiindex -->|"bundles"| node_monitor
node_gama -->|"connects to"| node_gamaext
node_models -->|"loads"| node_demo
node_models -->|"controls"| node_gama
node_players -->|"coordinates"| node_gama
node_android -->|"controls"| node_androidext
node_scrcpy -->|"streams"| node_scrcpyext
node_android -->|"orchestrates"| node_scrcpy
node_mdns -->|"discovers"| node_gamaext
node_monitor -->|"observes"| node_gamaext
node_selector -->|"lists"| node_models
node_manager -->|"controls"| node_players
node_stream -->|"drives"| node_android
node_wsmgr -->|"reflects"| node_players

click node_main "https://github.com/project-simple/simple.webplatform/blob/main/src/main.tsx"
click node_header "https://github.com/project-simple/simple.webplatform/blob/main/src/components/Header/Header.tsx"
click node_nav "https://github.com/project-simple/simple.webplatform/blob/main/src/components/Navigation/Navigation.tsx"
click node_lang "https://github.com/project-simple/simple.webplatform/blob/main/src/components/LanguageSelector/LanguageSelector.tsx"
click node_selector "https://github.com/project-simple/simple.webplatform/blob/main/src/components/SelectorSimulations/SelectorSimulations.tsx"
click node_manager "https://github.com/project-simple/simple.webplatform/blob/main/src/components/SimulationManager/SimulationManager.tsx"
click node_stream "https://github.com/project-simple/simple.webplatform/blob/main/src/components/StreamPlayerScreen/StreamPlayerScreen.tsx"
click node_wsmgr "https://github.com/project-simple/simple.webplatform/blob/main/src/components/WebSocketManager/WebSocketManager.tsx"
click node_vr "https://github.com/project-simple/simple.webplatform/blob/main/src/components/VRHeadset/VRHeadset.tsx"
click node_screenmode "https://github.com/project-simple/simple.webplatform/blob/main/src/components/ScreenModeContext/ScreenModeContext.tsx"
click node_redux "https://github.com/project-simple/simple.webplatform/blob/main/src/redux/store.ts"
click node_i18n "https://github.com/project-simple/simple.webplatform/blob/main/src/i18next/i18n.js"
click node_apiindex "https://github.com/project-simple/simple.webplatform/blob/main/src/api/index.ts"
click node_core "https://github.com/project-simple/simple.webplatform/blob/main/src/api/core/Controller.ts"
click node_gama "https://github.com/project-simple/simple.webplatform/blob/main/src/api/simulation/GamaConnector.ts"
click node_models "https://github.com/project-simple/simple.webplatform/blob/main/src/api/simulation/ModelManager.ts"
click node_players "https://github.com/project-simple/simple.webplatform/blob/main/src/api/multiplayer/PlayerManager.ts"
click node_android "https://github.com/project-simple/simple.webplatform/blob/main/src/api/android/adb/AdbManager.ts"
click node_scrcpy "https://github.com/project-simple/simple.webplatform/blob/main/src/api/android/scrcpy/ScrcpyServer.ts"
click node_mdns "https://github.com/project-simple/simple.webplatform/blob/main/src/api/infra/mDnsService.ts"
click node_monitor "https://github.com/project-simple/simple.webplatform/blob/main/src/api/monitoring/MonitorServer.ts"
click node_demo "https://github.com/project-simple/simple.webplatform/blob/main/learning-packages/demo/settings.json"

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_main,node_header,node_nav,node_lang,node_selector,node_manager,node_stream,node_wsmgr,node_vr,node_screenmode,node_redux,node_i18n toneBlue
class node_apiindex,node_core,node_gama,node_models,node_players,node_android,node_scrcpy,node_mdns,node_monitor toneAmber
class node_demo toneMint
class node_gamaext,node_androidext,node_scrcpyext toneRose
```

## Components

### Frontend app

React UI, reusable screens, and app state.

- [App entry](https://github.com/project-simple/simple.webplatform/blob/main/src/main.tsx): React/Vite entry · Bootstraps the client app. · `src/main.tsx`
- [Shell header](https://github.com/project-simple/simple.webplatform/blob/main/src/components/Header/Header.tsx): UI shell · Top-level navigation and branding. · `src/components/Header/Header.tsx`
- [Navigation](https://github.com/project-simple/simple.webplatform/blob/main/src/components/Navigation/Navigation.tsx): UI shell · Primary and compact navigation controls. · `src/components/Navigation/Navigation.tsx`
- [Language picker](https://github.com/project-simple/simple.webplatform/blob/main/src/components/LanguageSelector/LanguageSelector.tsx): i18n UI · Switches application language. · `src/components/LanguageSelector/LanguageSelector.tsx`
- [Simulation picker](https://github.com/project-simple/simple.webplatform/blob/main/src/components/SelectorSimulations/SelectorSimulations.tsx): screen · Lists available experiments to launch. · `src/components/SelectorSimulations/SelectorSimulations.tsx`
- [Simulation manager](https://github.com/project-simple/simple.webplatform/blob/main/src/components/SimulationManager/SimulationManager.tsx): screen · Controls running simulations and players. · `src/components/SimulationManager/SimulationManager.tsx`
- [Stream screen](https://github.com/project-simple/simple.webplatform/blob/main/src/components/StreamPlayerScreen/StreamPlayerScreen.tsx): screen · Displays live remote video or session output. · `src/components/StreamPlayerScreen/StreamPlayerScreen.tsx`
- [Stream bridge](https://github.com/project-simple/simple.webplatform/blob/main/src/components/WebSocketManager/WebSocketManager.tsx): stream UI · WebSocket-backed video and player canvas handling. · `src/components/WebSocketManager/WebSocketManager.tsx`
- [VR headset](https://github.com/project-simple/simple.webplatform/blob/main/src/components/VRHeadset/VRHeadset.tsx): VR UI · VR-oriented interaction surface. · `src/components/VRHeadset/VRHeadset.tsx`
- [Screen mode](https://github.com/project-simple/simple.webplatform/blob/main/src/components/ScreenModeContext/ScreenModeContext.tsx): context/store · Layout and display mode state. · `src/components/ScreenModeContext/ScreenModeContext.tsx`
- [Redux store](https://github.com/project-simple/simple.webplatform/blob/main/src/redux/store.ts): state · Global application state container. · `src/redux/store.ts`
- [Translations](https://github.com/project-simple/simple.webplatform/blob/main/src/i18next/i18n.js): i18n · Language catalog and initialization. · `src/i18next/i18n.js`

### Integration layer

Browser-facing services that connect to external systems.

- [API facade](https://github.com/project-simple/simple.webplatform/blob/main/src/api/index.ts): integration entry · Exports the service layer used by the UI. · `src/api/index.ts`
- [Core control](https://github.com/project-simple/simple.webplatform/blob/main/src/api/core/Controller.ts): shared API · Shared controller and constants. · `src/api/core/Controller.ts`
- [GAMA connector](https://github.com/project-simple/simple.webplatform/blob/main/src/api/simulation/GamaConnector.ts): simulation API · Connects to and manages simulation servers. · `src/api/simulation/GamaConnector.ts`
- [Model manager](https://github.com/project-simple/simple.webplatform/blob/main/src/api/simulation/ModelManager.ts): simulation API · Loads and tracks experiment models. · `src/api/simulation/ModelManager.ts`
- [Player manager](https://github.com/project-simple/simple.webplatform/blob/main/src/api/multiplayer/PlayerManager.ts): multiplayer API · Coordinates players and sessions. · `src/api/multiplayer/PlayerManager.ts`
- [Android bridge](https://github.com/project-simple/simple.webplatform/blob/main/src/api/android/adb/AdbManager.ts): device API · ADB and device discovery integration. · `src/api/android/adb/AdbManager.ts`
- [Scrcpy server](https://github.com/project-simple/simple.webplatform/blob/main/src/api/android/scrcpy/ScrcpyServer.ts): device API · Controls mirrored device streaming. · `src/api/android/scrcpy/ScrcpyServer.ts`
- [mDNS discovery](https://github.com/project-simple/simple.webplatform/blob/main/src/api/infra/mDnsService.ts): infra API · Finds local services and devices. · `src/api/infra/mDnsService.ts`
- [Monitor server](https://github.com/project-simple/simple.webplatform/blob/main/src/api/monitoring/MonitorServer.ts): monitoring API · Observes system and simulation status. · `src/api/monitoring/MonitorServer.ts`

### Experiment content

Bundled GAMA demo models and assets.

- [Demo library](https://github.com/project-simple/simple.webplatform/blob/main/learning-packages/demo/settings.json): GAMA content · Bundled experiment models and assets. · `learning-packages/demo/settings.json`

### External runtimes

Systems the platform orchestrates or monitors.

- **GAMA server**: external runtime · Runs simulations and exposes control endpoints.
- **Android device**: external runtime · Physical device mirrored or controlled remotely.
- **scrcpy runtime**: external runtime · Device screen streaming runtime.

## Connections

- App entry → Shell header: renders · App entry mounts the shell.
- App entry → Simulation picker: routes to · Main UI exposes simulation selection.
- App entry → Simulation manager: routes to · Main UI exposes simulation control.
- App entry → Stream screen: routes to · Main UI exposes live stream views.
- Shell header → Navigation: contains · Shell header includes navigation.
- Shell header → Language picker: contains · Shell header includes language switching.
- Simulation picker → Redux store: reads state · Selection view uses global app state.
- Simulation manager → Redux store: reads state · Manager view uses global app state.
- Stream screen → Stream bridge: uses · Stream screen is driven by WebSocket manager.
- Stream bridge → Screen mode: uses · Streaming UI responds to screen mode.
- Redux store → Screen mode: includes · Global state includes screen mode slice.
- Redux store → Translations: coordinates · App state and translations are used together in the UI.
- API facade → Core control: bundles · Integration facade exposes shared core pieces.
- API facade → GAMA connector: bundles · Integration facade exposes simulation connectivity.
- API facade → Player manager: bundles · Integration facade exposes multiplayer coordination.
- API facade → Android bridge: bundles · Integration facade exposes device control.
- API facade → Monitor server: bundles · Integration facade exposes monitoring.
- GAMA connector → GAMA server: connects to · Simulation connector talks to the GAMA server.
- Model manager → Demo library: loads · Model manager reads bundled experiments.
- Model manager → GAMA connector: controls · Model lifecycle is pushed through GAMA connector.
- Player manager → GAMA connector: coordinates · Players are tied to running simulations.
- Android bridge → Android device: controls · ADB manager controls physical devices.
- Scrcpy server → scrcpy runtime: streams · Scrcpy wrapper launches or controls mirroring.
- Android bridge → Scrcpy server: orchestrates · Device manager coordinates mirroring pipeline.
- mDNS discovery → GAMA server: discovers · Local discovery helps find reachable services.
- Monitor server → GAMA server: observes · Monitoring reads simulation/server status.
- Simulation picker → Model manager: lists · Simulation chooser is populated from available models.
- Simulation manager → Player manager: controls · Manager UI manipulates players and sessions.
- Stream screen → Android bridge: drives · Streaming screen can control device-backed sessions.
- Stream bridge → Player manager: reflects · Live stream/session state mirrors player coordination.
