Architecture

Principles

• Local-first: backend binds to localhost by default.
• One-way safety by design: remote source to local destination.
• Operational clarity: job state and service state are visible in one console.
• Lightweight backend with pragmatic frontend tooling.

System Components

1. app/backend/server.py
2. Local HTTP API + static asset server
3. Job lifecycle orchestration
4. Retry/backoff logic with network-failure classification
5. Rsync capability detection and command fallback behavior
6. Service-level pause/resume control

7. Diagnostics, history, and setup action endpoints

8. app/frontend/src/* (React + Vite + Tailwind)

9. Multi-screen operations console (Overview, Jobs, Locations, Builder, Logs, Setup)
10. Polling/state orchestration and API integration
11. Theme presets (Terminal, Fancy) and compact mode

12. Basic/Advanced/Expert builder modes

13. app/menubar/RsyncWebAppMenuBar.swift

14. Native macOS status item (rsync.wa)
15. Open/start/stop/restart/status controls

16. Update check + updater action integration

17. bin/*.sh and platform helpers

18. Service lifecycle scripts
19. Setup/install scripts (dependencies, launchagent, shortcuts, menu bar)
20. Update scripts

Persistence Model

• Jobs: profiles/jobs.json
• Location profiles: profiles/locations.json
• Runtime history/events: state/rsync-webapp.db (SQLite)
• Service settings: state/service-settings.json
• Logs: state/logs/

Security Model

• Input validation before command construction
• Absolute path constraints (remote and local)
• One-way-safety guardrails on rsync args
• Mirror mode requires explicit delete confirmation
• Mutating endpoints enforce localhost-origin checks
• Security response headers enabled
• Intended local-only usage (127.0.0.1)