How project-simple/simple.webplatform works
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: index.ts API facade · main.tsx App entry · store.ts Redux store · AdbManager.ts Android bridge
Components 25
Frontend app
React UI, reusable screens, and app state.
- App entry · Bootstraps the client app.
src/main.tsx - Shell header · Top-level navigation and branding.
src/components/Header/Header.tsx - Navigation · Primary and compact navigation controls.
src/components/Navigation/Navigation.tsx - Language picker · Switches application language.
src/components/LanguageSelector/LanguageSelector.tsx - Simulation picker · Lists available experiments to launch.
src/components/SelectorSimulations/SelectorSimulations.tsx - Simulation manager · Controls running simulations and players.
src/components/SimulationManager/SimulationManager.tsx - Stream screen · Displays live remote video or session output.
src/components/StreamPlayerScreen/StreamPlayerScreen.tsx - Stream bridge · WebSocket-backed video and player canvas handling.
src/components/WebSocketManager/WebSocketManager.tsx - VR headset · VR-oriented interaction surface.
src/components/VRHeadset/VRHeadset.tsx - Screen mode · Layout and display mode state.
src/components/ScreenModeContext/ScreenModeContext.tsx - Redux store · Global application state container.
src/redux/store.ts - Translations · Language catalog and initialization.
src/i18next/i18n.js
Integration layer
Browser-facing services that connect to external systems.
- API facade · Exports the service layer used by the UI.
src/api/index.ts - Core control · Shared controller and constants.
src/api/core/Controller.ts - GAMA connector · Connects to and manages simulation servers.
src/api/simulation/GamaConnector.ts - Model manager · Loads and tracks experiment models.
src/api/simulation/ModelManager.ts - Player manager · Coordinates players and sessions.
src/api/multiplayer/PlayerManager.ts - Android bridge · ADB and device discovery integration.
src/api/android/adb/AdbManager.ts - Scrcpy server · Controls mirrored device streaming.
src/api/android/scrcpy/ScrcpyServer.ts - mDNS discovery · Finds local services and devices.
src/api/infra/mDnsService.ts - Monitor server · Observes system and simulation status.
src/api/monitoring/MonitorServer.ts
Experiment content
Bundled GAMA demo models and assets.
- Demo library · Bundled experiment models and assets.
learning-packages/demo/settings.json
External runtimes
Systems the platform orchestrates or monitors.
- GAMA server · Runs simulations and exposes control endpoints.
- Android device · Physical device mirrored or controlled remotely.
- scrcpy runtime · Device screen streaming runtime.
Connections 30
- 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.