108 lines
5.7 KiB
Markdown
108 lines
5.7 KiB
Markdown
---
|
||
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: git-restore
|
||
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: null
|
||
created_at: '2026-08-19T18:49:38.284609+00:00'
|
||
updated_at: '2026-09-23T14:55:01.369679+00:00'
|
||
tags:
|
||
- architecture
|
||
- system‑design
|
||
- backend
|
||
- frontend
|
||
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
|
||
---
|
||
|
||
## 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`. |