How exussain/rfta0xe works
1. Top-level architecture
- This repo is a desktop client built with Tauri 2 + React + TypeScript, not just a web app.
- It has two main runtime pieces:
- the UI client that runs in the Tauri webview,
- a local Node.js snapshot server that serves the map data the UI depends on.
2. Primary runtime boundary
- In development, the React app runs on http://localhost:1420.
- The local data server runs on http://localhost:8787.
- The UI reads snapshot data from the server rather than crawling remote sources at runtime.
3. Desktop shell and platform layer
- src-tauri/ contains the native wrapper, Tauri configuration, capabilities, icons, and Windows packaging assets.
- There is a Windows-specific override config plus packaging for a portable build and installer-related files.
- The repo also bundles xray-core under src-tauri/xray-core, which matters as a Windows-side support component for proxy/network access.
4. UI composition
- The React app is organized into feature areas rather than a single monolith:
- src/map for map views,
- src/cyborg for the sci-fi HUD/operator interface,
- src/automator and src/cache for utility/operator pages,
- src/redhex for a separate visual/graphics mode,
- src/updater for app update handling,
- src/shell and src/shared-ui for common chrome and shell behavior.
- src/App.tsx and src/main.tsx are the main entry points tying these surfaces together.
5. Map subsystem
- The map is a core feature and is split into multiple pages:
- IranMapPage,
- TehranMapPage,
- SnapshotMapPage.
- Supporting pieces like MapCanvas, MapLegend, liveMarkers, and mapConfig handle rendering, overlays, and map-specific presentation.
- The map is clearly designed around snapshot-driven operational data, especially Tehran-focused features.
6. Data access layer
- src/data-access/ isolates all data-shape and fetch logic from the UI.
- It includes separate clients and types for:
- mahsa data,
- rfta data,
- mock snapshots for each domain,
- offline CSV and snapshot helpers,
- snapshot statistics.
- This layer is the boundary between the UI and the local/server data model.
7. Embedded and offline datasets
- The repo includes several static datasets under public/data/ and src/data-access/embedded/.
- Important files include CSV feature and layer exports plus saved-snapshot.json.
- This indicates the app supports offline/local-first rendering and does not depend exclusively on live upstream availability.
8. Snapshot server
- server/ is a dedicated Node-side subsystem for serving and maintaining the snapshot file.
- server/index.mjs exposes the API, snapshot-engine.mjs encapsulates snapshot logic, and append-snapshot.mjs refreshes or appends new data.
- The README states that /v1/rfta/snapshot/latest always returns the persisted local snapshot file rather than pulling live data on each request.
9. Snapshot update workflow
- Runtime reads are decoupled from snapshot refreshes.
- Refreshing happens through the append script, which checks upstream source changes, merges new features by feature.id, and rewrites the snapshot atomically.
- A systemd service/timer pair under server/systemd/ automates this on Ubuntu, making snapshot ingestion a scheduled backend job rather than an app responsibility.
10. Manual collector subproject
- manual-collector/ is a separate Node package with its own config and collector entrypoint.
- This looks like an auxiliary ingestion tool for manually gathering or reconstructing snapshot data when needed.
- It sits outside the main UI/runtime path, so it is best diagrammed as an operator or maintenance pipeline feeding the snapshot store.
11. Operator-oriented UI variants
- The src/cyborg/ area is a distinct HUD/console experience with panels, sliders, lighting, and a shared store.
- src/automator/, src/cache/, and src/updater/ suggest utility workflows for automation, cache maintenance, and app updates.
- These are separate feature surfaces, but they likely share the same shell and application state.
12. Styling and design system
- Global styling lives in src/styles/, with a dedicated rfta.css.
- src/assets/kit/ provides reusable visual assets for charts, icons, layout elements, and map imagery.
- The repo emphasizes a curated operator-themed visual system rather than generic UI components.
13. Development and deployment model
- The README describes a local development split: UI dev server + local API server.
- On Windows, the desktop app is launched via Tauri against the same workspace and uses a fixed 16:9 operator canvas design target.
- The build pipeline therefore has both browser-like dev testing and native desktop packaging concerns.
14. What to draw in an architecture diagram
- A good diagram would show:
- the React/Tauri desktop client as the primary user-facing layer,
- the local Node snapshot server as the data provider,
- the saved snapshot JSON/CSV files as the persistent data source,
- the append/collector pipeline as the refresh mechanism,
- and the systemd timer / Windows packaging extras as deployment-specific support components.
Main entry points: App.tsx App router · data-access Data access · IranMapPage.tsx Map pages · main.rs Tauri shell
Components 22
Desktop client
Tauri-hosted React UI and native shell
- App entry · Main UI entrypoint wiring the application shell
src/main.tsx - App router · Top-level composition and surface selection
src/App.tsx
UI surfaces
Primary operator-facing feature areas
- Shell chrome · Shared layout and clock/chrome behavior
src/shell/RftaShell.tsx - Shared UI · Reusable shell chrome and shared interface pieces
src/shared-ui/shellChrome.tsx - Map pages · Iran, Tehran, and snapshot map views
src/map/IranMapPage.tsx - Map canvas · Core map rendering and overlays
src/map/MapCanvas.tsx - Map legend · Map annotations and legend presentation
src/map/MapLegend.tsx - Cyborg HUD · Sci-fi operator console and panels
src/cyborg/CyborgPage.tsx - Automator · JSON automation workflow surface
src/automator/JsonAutomatorPage.tsx - Cache helper · Cache maintenance and helper workflow
src/cache/CacheHelperPage.tsx - RedHex mode · Alternate visual and neural canvas experience
src/redhex/RedHexPage.tsx - Updater UI · Application update handling experience
src/updater/UpdaterPage.tsx
Data layer
Client-side data access and embedded offline assets
- Data access · Typed clients and offline helpers bridging UI to data
src/data-access - Embedded data · Bundled CSV and snapshot datasets for local-first use
src/data-access/embedded - Public datasets · Runtime-served CSVs and persisted snapshot files
public/data/saved-snapshot.json
Snapshot server
Local Node service and refresh pipeline
- Snapshot API · Local server exposing latest persisted snapshot data
server/index.mjs - Snapshot engine · Snapshot normalization, merging, and persistence rules
server/snapshot-engine.mjs - Append job · Refreshes snapshots by appending new upstream features
server/append-snapshot.mjs - Manual collector · Separate Node package for operator-driven data collection
manual-collector/src/collector.mjs
Native support
Tauri wrapper and platform-specific packaging
- Tauri shell · Desktop host, capabilities, and platform configuration
src-tauri/src/main.rs - xray-core · Bundled Windows-side proxy and network support component
src-tauri/xray-core - Windows packaging · Windows-specific packaging and portable build assets
src-tauri/wix/startup.wxs
Connections 28
- App entry → App router: boots · Application entry initializes the root UI composition
- App router → Shell chrome: wraps · Root app renders the shared shell around feature surfaces
- App router → Map pages: routes · Root app exposes the map subsystem
- App router → Cyborg HUD: routes · Root app exposes the HUD/operator surface
- App router → Automator: routes · Root app exposes automation tools
- App router → Cache helper: routes · Root app exposes cache tooling
- App router → RedHex mode: routes · Root app exposes alternate visual mode
- App router → Updater UI: routes · Root app exposes update handling
- Shell chrome → Shared UI: uses · Shell chrome reuses shared interface components
- Map pages → Map canvas: renders · Map pages rely on the core canvas renderer
- Map pages → Map legend: annotates · Map pages use legends and overlays
- Map pages → Data access: reads · Map views consume typed snapshot and domain data
- Cyborg HUD → Data access: reads · HUD panels share application data and state
- Automator → Data access: reads · Automation pages operate on the same data boundary
- Cache helper → Data access: reads · Cache tools query local data shapes and snapshots
- RedHex mode → Data access: reads · Visual mode uses the shared data boundary
- Updater UI → Tauri shell: updates · Updater flows coordinate with the desktop host
- Data access → Embedded data: fallback · Client layer can use embedded offline datasets
- Data access → Public datasets: loads · Client layer reads persisted snapshot and public CSV data
- Data access → Snapshot API: fetches · Primary runtime data comes from the local snapshot API
- Snapshot API → Snapshot engine: delegates · API layer uses snapshot engine for persistence and merge rules
- Append job → Snapshot engine: uses · Refresh job applies the same snapshot logic when updating data
- Append job → Public datasets: writes · Refresh job rewrites the persisted snapshot store
- Manual collector → Public datasets: feeds · Manual collection can populate or reconstruct local datasets
- Tauri shell → xray-core: bundles · Desktop build includes proxy/network support assets
- Tauri shell → Windows packaging: packages · Native shell includes Windows installer and portable build assets
- Tauri shell → App entry: hosts · Tauri hosts the React webview client
- Snapshot API → Public datasets: serves · Local API serves the persisted snapshot file to the UI