MemRelay/projects/4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0/curated/development/System Architecture Overview (Backend + Frontend).md

title, type, permalink, stable_id, scope, project_id, workspace_type, usage_profile_id, preference_context, document_type, revision, source_memory_ids, source_checkpoint_ids, source_file_ids, source_git_commit, source_git_commits, source_agent_sync_ids, model_connection, model_name, source_count, source_revisions, source_dispositions, cited_source_ids, job_cited_source_ids, conflicts, supersedes, preferences, source_cursor, source_hash, prompt_version, schema_version, curation_job_id, created_at, updated_at, tags, restored_from_commit

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

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.