You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: ARCHITECTURE.md
+46-3Lines changed: 46 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,21 @@ The project has been refactored from a monolithic bash structure into a compiled
33
33
34
34
1.**`VLX_FrameFlow` (The Client):** Exclusively deployed on Single Board Computers (like Orange Pi 5 Plus or Radxa Rock 5T). Responsible for hardware interactions: capturing video via v4l2, managing hostapd/networkd, and gathering GPS data. It serves the mTLS-protected API.
35
35
2.**`VLX_FrameFlow_SRV` (The Server):** Exclusively deployed on a Virtual Private Server (VPS). Lightweight, focusing strictly on relaying traffic, receiving bonded connections, and enforcing UFW firewall rules.
36
-
3.**`vlx_frontend` (The UI):** A standalone web server encapsulating a pre-built Svelte SPA (`//go:embed`). Designed to run remotely on an operator's machine or in the cloud to manage the Field Unit via secure APIs.
36
+
3.**`vlx_frontend` (The UI):** A standalone web server encapsulating a pre-built Svelte SPA (`//go:embed`). Designed to run remotely on an operator's machine or in the cloud to manage the Field Unit via secure APIs. The frontend utilizes parallel REST polling (`Promise.all`) to dynamically fetch backend state, features a semantic parser for translating systemd string statuses (e.g., 'active', 'inactive', 'failed'), organizes UI components via CSS Grid layout, and streams text console output utilizing an `ansi-to-html` converter for colorized logs.
37
+
38
+
## API Framework & Routing
39
+
40
+
The core API has transitioned to utilizing the highly performant `Gin` framework (`github.com/gin-gonic/gin`). HTTP routes are registered using native Gin handler signatures (`func(c *gin.Context)`) rather than wrapping standard `http.HandlerFunc` components. Global CORS middleware handles OPTIONS requests automatically.
41
+
42
+
### Operational Endpoints
43
+
44
+
The unprivileged user interacts with the backend components via a standardized REST API structured primarily as `/api/v1/<module>/{start,stop,status,reset}`. Key operational endpoints include:
45
+
46
+
-**`/api/v1/client/reset`**: Initiates a full reset of client networking and bonding.
47
+
-**`/api/v1/gps/start`\|`stop`\|`status`**: Manages the transient systemd user unit for the GPS telemetry process.
48
+
-**`/api/v1/mediamtx/start`\|`stop`\|`status`**: Controls the local MediaMTX static user service.
49
+
-**`/api/v1/cameraman/start`\|`stop`\|`status`**: Orchestrates FFmpeg encoding pipelines directly to the MediaMTX API.
50
+
-**`/api/v1/ap/start`\|`stop`\|`status`**: Triggers internal privilege escalation to manipulate `hostapd` and network interfaces.
37
51
38
52
## Unified Configuration Paradigm
39
53
@@ -65,11 +79,23 @@ To secure the connection between the remote `vlx_frontend` and the SBC's `VLX_Fr
65
79
66
80
### "Build as User, Run as Root"
67
81
68
-
To maintain security and FHS compliance, the suite enforces a strict compilation and deployment workflow:
82
+
The suite enforces a strict dichotomy between Client and Server roles regarding execution privilege and systemd architecture:
83
+
69
84
1.**Build:** Unprivileged compilation via `build.sh`.
70
85
2.**Install:** Executing the compiled binary as root triggers `internal/sysutils.InstallBinary()`.
71
86
3.**Deploy:** The binaries place themselves into `/opt/VLX_FrameFlow/bin/` and configure templates in `/opt/VLX_FrameFlow/etc/`.
72
-
4.**Run:** Background services execute as the dedicated, unprivileged `$FRAMEFLOW_USER` via `systemd --user` units to limit the blast radius.
87
+
4.**Run (CLIENT):** On the SBC/Field Unit, background services must strictly execute as the dedicated, unprivileged `$FRAMEFLOW_USER`. Systemd management uses User-Space Systemd (`systemctl --user`). Unit files are generated in `~/.config/systemd/user/` and explicitly target `default.target`. **Important:** Systemd Lingering (`loginctl enable-linger`) must be enabled by root during initial setup to allow background execution without an active SSH session.
88
+
5.**Run (SERVER):** On the VPS/Relay Node, the main daemon strictly requires `root` execution (UID 0) to orchestrate routing and UFW firewall rules. Systemd management uses System-Space Systemd (`/etc/systemd/system/`) and targets `multi-user.target`. To maintain security, the server relies on **Privilege Dropping** (`User=`, `Group=`) inside the unit templates for specific exposed services (like MediaMTX) to minimize the blast radius.
89
+
90
+
### AP Module Privilege Escalation Pattern
91
+
92
+
The Access Point (AP) module within the Client architecture necessitates modifying system-level network configurations (`hostapd`, `systemd-networkd`, `systemd-resolved`) which requires root access. However, the Client CLI operates as an unprivileged user.
93
+
94
+
To bridge this gap securely, the suite implements a strict internal privilege escalation pattern:
95
+
- Unprivileged CLI commands wrap themselves in `sudo` to call hidden internal operations (e.g., `_ap_system_ops`).
96
+
- These hidden operations are protected by absolute root guards (`if os.Geteuid() != 0 { log.Fatal(...) }`).
97
+
- Once inside the root context, functions executing system commands (like restarting services via `sysutils.RunCommand`) do not redundantly include `sudo`.
98
+
73
99
74
100
75
101
### Server API Command Forwarding
@@ -88,6 +114,23 @@ The dual-protocol nature ensures network reliability without cross-contamination
88
114
-**Shadowsocks (via MPTCP):** Handles all bonded outbound TCP internet traffic. This is used by the Client to reach the broader internet transparently via the proxy.
89
115
-**MLVPN (UDP):** Handles the high-bandwidth SRT streams and the secure, bidirectional internal telemetry and API command routing between the Server (`10.1.10.1`) and Client (`10.1.10.2`).
90
116
117
+
## Module-Specific Behaviors
118
+
119
+
The system implements several highly specific optimizations and fail-safes per module:
-**Fallback Format Selection:** Employs a linear absolute-difference algorithm against user-defined maximums (`CAM_MAX_RESOLUTION`, `CAM_MAX_FPS`) to intelligently select fallback video formats (preferring H.264 copy, then MJPEG, then YUYV) when exact formats are unavailable.
124
+
-**SQLite Concurrency:** The backend SQLite database (`modernc.org/sqlite`) is configured with `_pragma=journal_mode(WAL)` and `_pragma=busy_timeout(5000)` in its DSN to inherently prevent 'database is locked' boot race conditions during concurrent module initialization.
125
+
126
+
### GPS Telemetry
127
+
-**Socket Draining:** Implements a non-blocking TCP socket drain pattern against `gpsd` to prevent TCP buffer desynchronization and data lag typical of high-frequency positioning data.
128
+
-**Rate Limiting:** Enforces a strict 5-second rate limit on HTTP POST transmissions to external endpoints.
129
+
-**Transient Cleanup:** Actively manages transient systemd units, executing `systemctl --user reset-failed` during cleanup to prevent unit name conflicts.
130
+
131
+
### MediaMTX & Bonding (v2ray)
132
+
-**Dynamic Architecture Resolution:** During initialization and updates, the system dynamically checks `runtime.GOARCH` to resolve and download correct asset architectures. This strictly prevents "Exec format error" failures when deploying across heterogeneous ARM and x86_64 fleets.
133
+
91
134
## Filesystem Structure
92
135
93
136
Following Linux File Hierarchy Standard (FHS) best practices, the global installation path is centralized:
Copy file name to clipboardExpand all lines: README.md
+16-4Lines changed: 16 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,6 +16,13 @@ VLX FrameFlow is a modular Go-based suite designed to transform Debian-based **S
16
16
17
17
The suite operates via a main installation entry point compiled into a Go binary, internal Go packages, and runtime service managers. Process control is handled via **`systemd`**.
18
18
19
+
### Execution Privilege & Systemd Architecture
20
+
21
+
The system enforces a strict operational dichotomy based on the deployed role:
22
+
23
+
-**CLIENT (SBC/Field Unit):** Strictly operates as an unprivileged dedicated user (`frameflow_user`). Systemd management utilizes User-Space Systemd (`systemctl --user`), stores unit files in `~/.config/systemd/user/`, and explicitly targets `default.target`. Systemd Lingering must be enabled by root during installation.
24
+
-**SERVER (VPS/Relay Node):** Strictly requires `root` execution (UID 0) to manage routing and firewall rules. Systemd management utilizes System-Space Systemd (`/etc/systemd/system/`) and targets `multi-user.target`. It relies on Privilege Dropping (`User=`, `Group=`) inside the unit templates to secure exposed services like MediaMTX.
25
+
19
26
The suite uses a **multi-protocol bonding architecture**: UDP traffic is routed exclusively via MLVPN, and TCP traffic is aggregated using MPTCP with Shadowsocks-libev and v2ray-plugin acting as a transparent proxy.
20
27
21
28
### Core Structure
@@ -26,10 +33,15 @@ The project has evolved into a multi-binary ecosystem to ensure role-specific fu
The backend API is built using the highly performant **Gin** framework (`github.com/gin-gonic/gin`) serving a standardized REST structure (`/api/v1/...`).
42
+
43
+
The **Control Panel Frontend** is a compiled **Svelte** application. It dynamically polls the backend via parallel REST calls (`Promise.all`), features a semantic parser translating raw systemd statuses into visual states, and provides real-time streaming text consoles utilizing `ansi-to-html`.
-**`client reset`**: Restarts networking and bonding services.
147
+
-**`client reset`**: Restarts networking and bonding services. (Also exposed via `/api/v1/client/reset`).
136
148
-**`bonding`**: Displays MPTCP proxy and MLVPN tunnel status.
137
149
-**`AP start`**: Activates HostAP (hotspot) on the first Wi-Fi interface.
138
150
-**`AP stop`**: Stops HostAP and switches the first Wi-Fi interface back to managed client mode.
@@ -159,7 +171,7 @@ Manages video encoding pipelines. This service is best utilized in combination w
159
171
./vlx_frameflow mediamtx <start|stop|status>
160
172
```
161
173
162
-
Manages the local **MediaMTX** server (SRT protocol only). Combining this service with the suite's Access Point (AP) mode is crucial for achieving optimal performance and reliability when interfacing with devices running rigid or proprietary software, such as GoPro cameras.
174
+
Manages the local **MediaMTX** server (SRT protocol only). Combining this service with the suite's Access Point (AP) mode is crucial for achieving optimal performance and reliability when interfacing with devices running rigid or proprietary software, such as GoPro cameras. Also exposed via REST (`/api/v1/mediamtx/start|stop|status`).
163
175
164
176
**Functions:**
165
177
@@ -172,7 +184,7 @@ Manages the local **MediaMTX** server (SRT protocol only). Combining this servic
172
184
./vlx_frameflow gps <start|stop|status>
173
185
```
174
186
175
-
Manages GPS and telemetry services. This module acts as a resilient data pipeline, ensuring real-time location and telemetry data are consistently processed and transmitted regardless of network fluctuations.
187
+
Manages GPS and telemetry services. This module acts as a resilient data pipeline, ensuring real-time location and telemetry data are consistently processed and transmitted regardless of network fluctuations. Also exposed via REST (`/api/v1/gps/start|stop|status`).
0 commit comments