---
title: System Architecture Overview (Backend + Frontend)
type: curated
permalink: main/projects/4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0/curated/development/system-architecture-overview-backend-frontend
stable_id: faab1e63-b668-4362-896d-9a82ea81d348
scope: project
project_id: 4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0
workspace_type: development
usage_profile_id: null
preference_context: development
document_type: architecture
revision: 1
source_memory_ids: []
source_checkpoint_ids: []
source_file_ids: []
source_git_commit: de28dc8246094e2bc17cab7c764fb4d4a2da71e0
source_git_commits:
- de28dc8246094e2bc17cab7c764fb4d4a2da71e0
source_agent_sync_ids: []
model_connection: Sub2API
model_name: openai/gpt-oss-120b
source_count: 188
source_revisions: {}
source_dispositions:
  processed: 188
  unchanged: 0
  unsupported: 0
  skipped: 0
cited_source_ids:
- git:backend/Cargo.toml
- git:frontend/pnpm-lock.yaml
job_cited_source_ids:
- git:backend/Cargo.toml
- git:frontend/pnpm-lock.yaml
conflicts: []
supersedes: []
preferences: []
source_cursor: 87
source_hash: 96f0e4026558c8a03161f53b392fcec7359d4d701c4f33576b44e2f308b0ec5a
prompt_version: 2026-08-12.3
schema_version: '3'
curation_job_id: a9f69899-ee39-4900-b39a-a54d737f9614
created_at: '2026-08-19T18:49:38.284609+00:00'
updated_at: '2026-08-19T18:49:38.285207+00:00'
tags:
- architecture
- system‑design
- backend
- frontend
---

## 1. Backend Architecture (Rust)

- **Core Stack**: Rust 2021, Axum 0.8 (HTTP server), Tokio 1.48 (async runtime), `zbus` 5 for DBus communication with **ofono**.
- **Modules**:
  - `config.rs` – JSON‑based configuration with hot‑reload; aggregates webhook, SMS‑push, refresh, FRPC sub‑configs.
  - `db.rs` – Embedded SQLite (`rusqlite`) storing SMS and call history; protected by `Arc<Mutex<Connection>>`.
  - `dbus.rs` – Generated proxies for ofono interfaces; all calls go through the global serial lock (`with_serial`).
  - `handlers.rs` – HTTP API handlers exposing health, AT gateway, device info, USB mode, band‑lock, OTA, FRPC, webhook, SMS‑push, etc. All responses use a uniform JSON envelope.
  - `ota.rs` – Validates and installs OTA packages atomically; checks architecture, version monotonicity and checksums.
  - `state.rs` – FRPC lifecycle management (install, config render, start/stop, log rotation).
  - `usb_switch.rs` – Configfs‑based USB gadget re‑configuration; persistent mode stored in `/mnt/data/mode.cfg`.
  - `utils.rs` – Helpers for band‑mask conversion, system stats, AT response parsing.
- **Build Process**: Cross‑compiled on a Windows host using Docker (`docker/gnu-builder.Dockerfile`) targeting `aarch64-unknown-linux-gnu`. Build script (`build.rs`) injects `APP_VERSION`, `GIT_BRANCH`, `GIT_COMMIT`.
- **Docker Image**: Ubuntu 18.04 base with `gcc-aarch64-linux-gnu`; installs Rust toolchain and cross‑compiler.

**Key Design Decisions** (derived from evidence):
- Global serial lock to avoid `InProgress` DBus errors.
- iptables watchdog to clean stale NAT rules.
- All HTTP endpoints currently return `200 OK` (open issue).
- CORS set to `*` (development convenience, open issue).
- Sensitive fields are redacted in source code; secure storage is pending.

## 2. Front‑end Architecture (React 19 + TypeScript 5.9)

- **Build Tool**: Vite 7 with alias `@` → `src/*`. Injects compile‑time constants (`__APP_VERSION__`, `__GIT_COMMIT__`).
- **UI Library**: MUI v7 (Emotion styling engine). Theme persisted via `ThemeContext`.
- **State / Data Fetching**: `@tanstack/react-query` 5 for caching; custom `useApi` hook wraps `fetch` with timeout and error mapping.
- **Global Contexts**: `ThemeContext` (light/dark), `RefreshContext` (polling interval). Both persisted in `localStorage`.
- **Routing**: React Router lazy‑loaded routes for each page (Dashboard, ATConsole, Network, FRP, OTA, etc.).
- **Pages**:
  - **Dashboard** – Real‑time status overview, quick controls, system resource monitors.
  - **ATConsole** – Raw AT command gateway with history.
  - **Configuration** – Device toggles, USB mode selector, webhook & SMS‑push config.
  - **Network** – Cell list, band‑lock UI, APN editor, interface list.
  - **FRP** – FRPC client management (enable, auto‑start, config, logs).
  - **OTA Update** – OTA upload, validation table, apply/reboot actions.
  - **InitScript** – Edit and static‑analyse `init.sh`.
  - **Phone**, **SMS**, **Terminal**, … (additional functional pages).
- **Styling Guidelines**: Compact “label‑left / control‑right” for narrow fields; vertical layout for large sections; fixed header with inner scrolling.
- **Testing & Linting**: ESLint 9, strict TypeScript `strict` mode; no unit tests currently (open issue).

**Key Design Decisions** (frontend):
- Adaptive polling (`useAdaptivePolling`) scales interval by page visibility.
- Sensitive identifiers are blurred by default and togglable.
- All scripts must run on Windows (development platform).
- UI strings are Chinese‑language by default (communication language set in project metadata).

## 3. Build & Deployment

- `scripts/build.sh` – Cross‑compiles backend, builds frontend via Vite, optionally compresses with UPX, generates OTA meta.
- `scripts/pack-ota.sh` – Packages binaries, frontend `dist`, FRPC binary; creates `meta.json` with MD5/SHA‑256 checksums.
- CI (`.github/workflows/build-ota.yml`) runs the above, validates checksums, uploads artifacts.
- `scripts/deploy.sh` – Pushes OTA artifacts to device via ADB, stops running service, copies files.
- Docker image (`docker/gnu-builder.Dockerfile`) provides reproducible cross‑compile environment.

**Source IDs**: `git:backend/Cargo.toml`, `git:frontend/pnpm-lock.yaml`, `docker/gnu-builder.Dockerfile`.