How roiarthurb/simple.webplatform works
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: index.ts API entry · main.tsx App entry · components UI shell · SimulationManager Simulation manager
Components 18
Browser UI
React/Vite client side operator dashboard.
- App entry · Bootstraps the browser application and mounts the UI.
src/main.tsx - UI shell · Top-level header, navigation, footer, and language controls.
src/components - Simulation manager · Main operator surface for selecting and controlling simulations.
src/components/SimulationManager - Stream player · Displays remote device or simulation stream playback.
src/components/StreamPlayerScreen - WebSocket manager · Manages websocket status and live video/control transport in the UI.
src/components/WebSocketManager - VR headset · Headset-specific operator controls and status.
src/components/VRHeadset - Screen mode · Shared layout and display-mode state.
src/redux/screenModeSlice.ts - Localization · Initializes language handling for the multilingual UI.
src/i18next/i18n.js - Language packs · UI translations for supported operator languages.
src/languages
Node Services
Server-side APIs and operational integrations.
- API entry · Starts the backend service layer and wires runtime subsystems.
src/api/index.ts - Core controller · Central backend coordination and shared constants.
src/api/core/Controller.ts - GAMA bridge · Connects the platform to external GAMA Server models and control.
src/api/simulation - Player manager · Tracks multiplayer players and connection state.
src/api/multiplayer/PlayerManager.ts - ADB/Scrcpy · Discovers Android devices, prepares headsets, and starts scrcpy streaming.
src/api/android - Monitoring server · Exposes health and operational status reporting.
src/api/monitoring/MonitorServer.ts - Infra services · Static hosting, mDNS discovery, and UPS support.
src/api/infra - Decoder worker · Decodes scrcpy frames off the main thread.
src/workers/scrcpyDecoder.ts
Simulation Content
External model packages and demo assets loaded at runtime.
- Demo packages · GAMA demo models, GIS inputs, and runtime package data.
learning-packages/demo
Connections 23
- 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.