# exussain/rfta0xe architecture

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

- Interactive diagram: https://gitdiagram.com/exussain/rfta0xe
- Repository: https://github.com/exussain/rfta0xe

## Overview

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: [`src/App.tsx`](https://github.com/exussain/rfta0xe/blob/source-only/src/App.tsx) (App router), [`src/data-access`](https://github.com/exussain/rfta0xe/tree/source-only/src/data-access) (Data access), [`src/map/IranMapPage.tsx`](https://github.com/exussain/rfta0xe/blob/source-only/src/map/IranMapPage.tsx) (Map pages), [`src-tauri/src/main.rs`](https://github.com/exussain/rfta0xe/blob/source-only/src-tauri/src/main.rs) (Tauri shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop client"]
  node_app_entry["App entry<br/>React bootstrap<br/>[main.tsx]"]
  node_app_root["App router<br/>React composition<br/>[App.tsx]"]
end

subgraph group_ui["UI surfaces"]
  node_shell["Shell chrome<br/>UI shell<br/>[RftaShell.tsx]"]
  node_shared_ui["Shared UI<br/>common UI<br/>[shellChrome.tsx]"]
  node_map_pages["Map pages<br/>feature set<br/>[IranMapPage.tsx]"]
  node_map_canvas["Map canvas<br/>rendering<br/>[MapCanvas.tsx]"]
  node_map_legend["Map legend<br/>overlay<br/>[MapLegend.tsx]"]
  node_cyborg["Cyborg HUD<br/>feature surface<br/>[CyborgPage.tsx]"]
  node_automator["Automator<br/>utility page"]
  node_cache["Cache helper<br/>utility page"]
  node_redhex["RedHex mode<br/>visual mode<br/>[RedHexPage.tsx]"]
  node_updater["Updater UI<br/>update surface<br/>[UpdaterPage.tsx]"]
end

subgraph group_data["Data layer"]
  node_data_access["Data access<br/>client boundary"]
  node_embedded_data["Embedded data<br/>offline assets"]
  node_public_data["Public datasets<br/>static datasets"]
end

subgraph group_server["Snapshot server"]
  node_snapshot_server["Snapshot API<br/>node service<br/>[index.mjs]"]
  node_snapshot_engine["Snapshot engine<br/>merge logic"]
  node_append_job["Append job<br/>refresh script"]
  node_manual_collector["Manual collector<br/>ingestion tool<br/>[collector.mjs]"]
end

subgraph group_native["Native support"]
  node_tauri_shell["Tauri shell<br/>native wrapper<br/>[main.rs]"]
  node_xray_core["xray-core<br/>proxy support"]
  node_windows_packaging["Windows packaging<br/>installer assets<br/>[startup.wxs]"]
end

node_app_entry -->|"boots"| node_app_root
node_app_root -->|"wraps"| node_shell
node_app_root -->|"routes"| node_map_pages
node_app_root -->|"routes"| node_cyborg
node_app_root -->|"routes"| node_automator
node_app_root -->|"routes"| node_cache
node_app_root -->|"routes"| node_redhex
node_app_root -->|"routes"| node_updater
node_shell -->|"uses"| node_shared_ui
node_map_pages -->|"renders"| node_map_canvas
node_map_pages -->|"annotates"| node_map_legend
node_map_pages -->|"reads"| node_data_access
node_cyborg -->|"reads"| node_data_access
node_automator -->|"reads"| node_data_access
node_cache -->|"reads"| node_data_access
node_redhex -->|"reads"| node_data_access
node_updater -->|"updates"| node_tauri_shell
node_data_access -->|"fallback"| node_embedded_data
node_data_access -->|"loads"| node_public_data
node_data_access -->|"fetches"| node_snapshot_server
node_snapshot_server -->|"delegates"| node_snapshot_engine
node_append_job -->|"uses"| node_snapshot_engine
node_append_job -->|"writes"| node_public_data
node_manual_collector -->|"feeds"| node_public_data
node_tauri_shell -->|"bundles"| node_xray_core
node_tauri_shell -->|"packages"| node_windows_packaging
node_tauri_shell -->|"hosts"| node_app_entry
node_snapshot_server -->|"serves"| node_public_data

click node_app_entry "https://github.com/exussain/rfta0xe/blob/source-only/src/main.tsx"
click node_app_root "https://github.com/exussain/rfta0xe/blob/source-only/src/App.tsx"
click node_shell "https://github.com/exussain/rfta0xe/blob/source-only/src/shell/RftaShell.tsx"
click node_shared_ui "https://github.com/exussain/rfta0xe/blob/source-only/src/shared-ui/shellChrome.tsx"
click node_map_pages "https://github.com/exussain/rfta0xe/blob/source-only/src/map/IranMapPage.tsx"
click node_map_canvas "https://github.com/exussain/rfta0xe/blob/source-only/src/map/MapCanvas.tsx"
click node_map_legend "https://github.com/exussain/rfta0xe/blob/source-only/src/map/MapLegend.tsx"
click node_cyborg "https://github.com/exussain/rfta0xe/blob/source-only/src/cyborg/CyborgPage.tsx"
click node_automator "https://github.com/exussain/rfta0xe/blob/source-only/src/automator/JsonAutomatorPage.tsx"
click node_cache "https://github.com/exussain/rfta0xe/blob/source-only/src/cache/CacheHelperPage.tsx"
click node_redhex "https://github.com/exussain/rfta0xe/blob/source-only/src/redhex/RedHexPage.tsx"
click node_updater "https://github.com/exussain/rfta0xe/blob/source-only/src/updater/UpdaterPage.tsx"
click node_data_access "https://github.com/exussain/rfta0xe/tree/source-only/src/data-access"
click node_embedded_data "https://github.com/exussain/rfta0xe/tree/source-only/src/data-access/embedded"
click node_public_data "https://github.com/exussain/rfta0xe/blob/source-only/public/data/saved-snapshot.json"
click node_snapshot_server "https://github.com/exussain/rfta0xe/blob/source-only/server/index.mjs"
click node_snapshot_engine "https://github.com/exussain/rfta0xe/blob/source-only/server/snapshot-engine.mjs"
click node_append_job "https://github.com/exussain/rfta0xe/blob/source-only/server/append-snapshot.mjs"
click node_manual_collector "https://github.com/exussain/rfta0xe/blob/source-only/manual-collector/src/collector.mjs"
click node_tauri_shell "https://github.com/exussain/rfta0xe/blob/source-only/src-tauri/src/main.rs"
click node_xray_core "https://github.com/exussain/rfta0xe/tree/source-only/src-tauri/xray-core"
click node_windows_packaging "https://github.com/exussain/rfta0xe/blob/source-only/src-tauri/wix/startup.wxs"

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_app_entry,node_app_root toneBlue
class node_shell,node_shared_ui,node_map_pages,node_map_canvas,node_map_legend,node_cyborg,node_automator,node_cache,node_redhex,node_updater toneAmber
class node_data_access,node_embedded_data,node_public_data toneMint
class node_snapshot_server,node_snapshot_engine,node_append_job,node_manual_collector toneRose
class node_tauri_shell,node_xray_core,node_windows_packaging toneIndigo
```

## Components

### Desktop client

Tauri-hosted React UI and native shell

- [App entry](https://github.com/exussain/rfta0xe/blob/source-only/src/main.tsx): React bootstrap · Main UI entrypoint wiring the application shell · `src/main.tsx`
- [App router](https://github.com/exussain/rfta0xe/blob/source-only/src/App.tsx): React composition · Top-level composition and surface selection · `src/App.tsx`

### UI surfaces

Primary operator-facing feature areas

- [Shell chrome](https://github.com/exussain/rfta0xe/blob/source-only/src/shell/RftaShell.tsx): UI shell · Shared layout and clock/chrome behavior · `src/shell/RftaShell.tsx`
- [Shared UI](https://github.com/exussain/rfta0xe/blob/source-only/src/shared-ui/shellChrome.tsx): common UI · Reusable shell chrome and shared interface pieces · `src/shared-ui/shellChrome.tsx`
- [Map pages](https://github.com/exussain/rfta0xe/blob/source-only/src/map/IranMapPage.tsx): feature set · Iran, Tehran, and snapshot map views · `src/map/IranMapPage.tsx`
- [Map canvas](https://github.com/exussain/rfta0xe/blob/source-only/src/map/MapCanvas.tsx): rendering · Core map rendering and overlays · `src/map/MapCanvas.tsx`
- [Map legend](https://github.com/exussain/rfta0xe/blob/source-only/src/map/MapLegend.tsx): overlay · Map annotations and legend presentation · `src/map/MapLegend.tsx`
- [Cyborg HUD](https://github.com/exussain/rfta0xe/blob/source-only/src/cyborg/CyborgPage.tsx): feature surface · Sci-fi operator console and panels · `src/cyborg/CyborgPage.tsx`
- [Automator](https://github.com/exussain/rfta0xe/blob/source-only/src/automator/JsonAutomatorPage.tsx): utility page · JSON automation workflow surface · `src/automator/JsonAutomatorPage.tsx`
- [Cache helper](https://github.com/exussain/rfta0xe/blob/source-only/src/cache/CacheHelperPage.tsx): utility page · Cache maintenance and helper workflow · `src/cache/CacheHelperPage.tsx`
- [RedHex mode](https://github.com/exussain/rfta0xe/blob/source-only/src/redhex/RedHexPage.tsx): visual mode · Alternate visual and neural canvas experience · `src/redhex/RedHexPage.tsx`
- [Updater UI](https://github.com/exussain/rfta0xe/blob/source-only/src/updater/UpdaterPage.tsx): update surface · Application update handling experience · `src/updater/UpdaterPage.tsx`

### Data layer

Client-side data access and embedded offline assets

- [Data access](https://github.com/exussain/rfta0xe/tree/source-only/src/data-access): client boundary · Typed clients and offline helpers bridging UI to data · `src/data-access`
- [Embedded data](https://github.com/exussain/rfta0xe/tree/source-only/src/data-access/embedded): offline assets · Bundled CSV and snapshot datasets for local-first use · `src/data-access/embedded`
- [Public datasets](https://github.com/exussain/rfta0xe/blob/source-only/public/data/saved-snapshot.json): static datasets · Runtime-served CSVs and persisted snapshot files · `public/data/saved-snapshot.json`

### Snapshot server

Local Node service and refresh pipeline

- [Snapshot API](https://github.com/exussain/rfta0xe/blob/source-only/server/index.mjs): node service · Local server exposing latest persisted snapshot data · `server/index.mjs`
- [Snapshot engine](https://github.com/exussain/rfta0xe/blob/source-only/server/snapshot-engine.mjs): merge logic · Snapshot normalization, merging, and persistence rules · `server/snapshot-engine.mjs`
- [Append job](https://github.com/exussain/rfta0xe/blob/source-only/server/append-snapshot.mjs): refresh script · Refreshes snapshots by appending new upstream features · `server/append-snapshot.mjs`
- [Manual collector](https://github.com/exussain/rfta0xe/blob/source-only/manual-collector/src/collector.mjs): ingestion tool · Separate Node package for operator-driven data collection · `manual-collector/src/collector.mjs`

### Native support

Tauri wrapper and platform-specific packaging

- [Tauri shell](https://github.com/exussain/rfta0xe/blob/source-only/src-tauri/src/main.rs): native wrapper · Desktop host, capabilities, and platform configuration · `src-tauri/src/main.rs`
- [xray-core](https://github.com/exussain/rfta0xe/tree/source-only/src-tauri/xray-core): proxy support · Bundled Windows-side proxy and network support component · `src-tauri/xray-core`
- [Windows packaging](https://github.com/exussain/rfta0xe/blob/source-only/src-tauri/wix/startup.wxs): installer assets · Windows-specific packaging and portable build assets · `src-tauri/wix/startup.wxs`

## Connections

- 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
