ARCHITECTURE.adoc

Cloud Sync Tuner Architecture

Table of Contents

• Layer Diagram
• Seam Analysis
  • High Friction Points (smoothed)
  • Attack Surface Reduction
• Platform Compatibility
• Build Matrix

Layer Diagram

┌─────────────────────────────────────────────────────────────────┐
│                     LAYER 1: User Interface                     │
│                  Ada TUI / CLI (cloud_sync_tuner)               │
│  Seam: config.toml parsing, input validation                    │
└─────────────────────────────┬───────────────────────────────────┘
                              │ Cache mode selection
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   LAYER 2: Service Generator                    │
│              Template expansion → .service files                │
│  Seam: Path substitution, rate limit injection                  │
└─────────────────────────────┬───────────────────────────────────┘
                              │ systemd unit files
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   LAYER 3: Container Runtime                    │
│              Wolfi image / nerdctl / podman                     │
│  Seam: Volume mounts, capability management                     │
└─────────────────────────────┬───────────────────────────────────┘
                              │ FUSE mount requests
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     LAYER 4: Network/SDP                        │
│              WireGuard tunnel / cicada identity                 │
│  Seam: Key exchange, tunnel establishment                       │
└─────────────────────────────┬───────────────────────────────────┘
                              │ Encrypted traffic
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   LAYER 5: Cloud Backends                       │
│                    rclone → Dropbox/GDrive/OneDrive             │
│  Seam: OAuth tokens, rate limit handling                        │
└─────────────────────────────────────────────────────────────────┘

Seam Analysis

High Friction Points (smoothed)

Seam	Issue	Resolution
TUI → Generator	Hard-coded paths	config.toml with ${VAR} expansion
Container → Host	SYS_ADMIN capability	Rootless mode, minimal capabilities
VPN → Cloud	Static IP AllowedIPs	DNS-based routing, split tunnel

Attack Surface Reduction

Layer	Risk	Mitigation
Container	Privilege escalation	--cap-drop=ALL --cap-add=SYS_ADMIN (FUSE only)
VPN	Key compromise	cicada post-quantum keys, auto-rotation
Cloud	Token theft	Encrypted rclone.conf, short-lived tokens

Platform Compatibility

Platform	Container	Native	Notes
Linux (all arch)	✓	✓	Full support
macOS	✓ (VM)	✓	Rosetta for arm64
Windows	✓ (WSL2)	❌	Native GNAT exists but FUSE doesn’t
Android	Limited	✓	Termux build, no FUSE
iOS	❌	Possible	Needs Swift wrapper, no FUSE
Minix	❌	Needs C port	libcurl-based alternative needed

Build Matrix

For maximum portability, maintain two codebases:

1. Ada version (this repo) - Linux/macOS/FreeBSD containers

2. C/libcurl version (future) - iOS/Minix/embedded

The C version would share: - config.toml format - Service file templates - Rate limit constants