# rtariq2015/raspi-cloud-sync-pro architecture

> Architecture diagram of the GitHub repository rtariq2015/raspi-cloud-sync-pro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rtariq2015/raspi-cloud-sync-pro
- Repository: https://github.com/rtariq2015/raspi-cloud-sync-pro

## Overview

Raspi Cloud Sync Pro turns a Raspberry Pi into a USB file-capture appliance with local retention and verified cloud backups. The main workflow is Windows copy and safe Eject, guarded capture into durable staging, then a background worker that uploads and verifies files over built-in Wi-Fi. Distinct supporting capabilities include experimental MTP and optional Samba ingestion, dashboard access, and Google web setup. Edges reflect README-described flows or relationships visible in the supplied source index and excerpts; several listed subsystems were not sampled in full.

Main entry points: [`src/raspi_cloud_sync_pro/mass_storage_appliance.py`](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/mass_storage_appliance.py) (Mass-storage appliance), [`src/raspi_cloud_sync_pro/staged_worker.py`](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/staged_worker.py) (Backup worker), [`src/raspi_cloud_sync_pro/staging.py`](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/staging.py) (Durable staging), [`src/raspi_cloud_sync_pro/dashboard.py`](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/dashboard.py) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_usb_capture["USB capture"]
  node_msc_appliance["Mass-storage appliance"]
  node_gadget["USB gadget control<br/>[gadget.py]"]
  node_linux_gadget["Linux gadget backend<br/>[linux_gadget.py]"]
  node_image_enrollment["Image enrollment"]
  node_image_policy["Image policy"]
  node_ownership["Storage ownership<br/>[storage.py]"]
  node_capture_space["Capture admission<br/>[capture_space.py]"]
  node_mtp["MTP ingestion<br/>[mtp_ingest.py]"]
  node_smb["Samba ingestion<br/>[smb_ingest.py]"]
end

subgraph group_backup["Backup pipeline"]
  node_staging["Durable staging<br/>[staging.py]"]
  node_worker["Backup worker<br/>[staged_worker.py]"]
  node_engine["Backup engine<br/>[engine.py]"]
  node_history[("Backup history<br/>[history.py]")]
end

subgraph group_cloud_setup["Cloud integrations"]
  node_google_dispatch["Google upload dispatch"]
  node_google_broker["Google setup broker<br/>[google_broker.py]"]
  node_google_destination["Google destination"]
end

subgraph group_access["Dashboard and networking"]
  node_network["Wi-Fi policy<br/>[network.py]"]
  node_dashboard["Dashboard<br/>[dashboard.py]"]
end

node_windows(("Windows host"))
node_google_drive[("Google Drive")]
node_browser(("Owner or viewer"))

node_windows -->|"copies and ejects"| node_msc_appliance
node_msc_appliance -->|"controls gadget"| node_gadget
node_gadget -->|"uses backend"| node_linux_gadget
node_msc_appliance -->|"captures files"| node_staging
node_msc_appliance -->|"guards capture"| node_ownership
node_msc_appliance -->|"checks capacity"| node_capture_space
node_image_enrollment -->|"validates image"| node_image_policy
node_mtp -->|"publishes batches"| node_staging
node_smb -->|"stages files"| node_staging
node_staging -->|"queues batches"| node_worker
node_worker -->|"runs backup"| node_engine
node_engine -->|"records status"| node_history
node_worker -->|"checks connectivity"| node_network
node_worker -->|"dispatches uploads"| node_google_dispatch
node_google_dispatch -->|"uses destination"| node_google_destination
node_google_destination -->|"uploads and verifies"| node_google_drive
node_google_broker -.->|"prepares destination"| node_google_destination
node_browser -->|"browses files"| node_dashboard
node_dashboard -->|"shows backup history"| node_history
node_dashboard -.->|"requests setup"| node_google_broker

click node_msc_appliance "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/mass_storage_appliance.py"
click node_gadget "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/gadget.py"
click node_linux_gadget "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/linux_gadget.py"
click node_image_enrollment "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/image_enrollment.py"
click node_image_policy "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/mass_storage_image.py"
click node_ownership "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/storage.py"
click node_capture_space "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/capture_space.py"
click node_staging "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/staging.py"
click node_mtp "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/mtp_ingest.py"
click node_smb "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/smb_ingest.py"
click node_worker "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/staged_worker.py"
click node_engine "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/engine.py"
click node_history "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/history.py"
click node_network "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/network.py"
click node_google_dispatch "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/google_upload_dispatcher.py"
click node_google_broker "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/google_broker.py"
click node_google_destination "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/google_destination.py"
click node_dashboard "https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/dashboard.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_msc_appliance,node_gadget,node_linux_gadget,node_image_enrollment,node_image_policy,node_ownership,node_capture_space,node_mtp,node_smb,node_browser toneBlue
class node_staging,node_worker,node_engine,node_history,node_google_drive toneAmber
class node_google_dispatch,node_google_broker,node_google_destination toneMint
class node_network,node_dashboard toneRose
class node_windows toneIndigo
```

## Components

### USB capture

- [Mass-storage appliance](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/mass_storage_appliance.py): `src/raspi_cloud_sync_pro/mass_storage_appliance.py`
- [USB gadget control](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/gadget.py): `src/raspi_cloud_sync_pro/gadget.py`
- [Linux gadget backend](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/linux_gadget.py): `src/raspi_cloud_sync_pro/linux_gadget.py`
- [Image enrollment](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/image_enrollment.py): `src/raspi_cloud_sync_pro/image_enrollment.py`
- [Image policy](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/mass_storage_image.py): `src/raspi_cloud_sync_pro/mass_storage_image.py`
- [Storage ownership](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/storage.py): `src/raspi_cloud_sync_pro/storage.py`
- [Capture admission](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/capture_space.py): `src/raspi_cloud_sync_pro/capture_space.py`
- [MTP ingestion](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/mtp_ingest.py): `src/raspi_cloud_sync_pro/mtp_ingest.py`
- [Samba ingestion](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/smb_ingest.py): `src/raspi_cloud_sync_pro/smb_ingest.py`

### Backup pipeline

- [Durable staging](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/staging.py): `src/raspi_cloud_sync_pro/staging.py`
- [Backup worker](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/staged_worker.py): `src/raspi_cloud_sync_pro/staged_worker.py`
- [Backup engine](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/engine.py): `src/raspi_cloud_sync_pro/engine.py`
- [Backup history](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/history.py): `src/raspi_cloud_sync_pro/history.py`

### Cloud integrations

- [Google upload dispatch](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/google_upload_dispatcher.py): `src/raspi_cloud_sync_pro/google_upload_dispatcher.py`
- [Google setup broker](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/google_broker.py): `src/raspi_cloud_sync_pro/google_broker.py`
- [Google destination](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/google_destination.py): `src/raspi_cloud_sync_pro/google_destination.py`

### Dashboard and networking

- [Wi-Fi policy](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/network.py): `src/raspi_cloud_sync_pro/network.py`
- [Dashboard](https://github.com/rtariq2015/raspi-cloud-sync-pro/blob/development/src/raspi_cloud_sync_pro/dashboard.py): `src/raspi_cloud_sync_pro/dashboard.py`

### Other components

- **Windows host**
- **Google Drive**
- **Owner or viewer**

## Connections

- Windows host → Mass-storage appliance: copies and ejects
- Mass-storage appliance → USB gadget control: controls gadget (evidence: `src/raspi_cloud_sync_pro/mass_storage_appliance.py`)
- USB gadget control → Linux gadget backend: uses backend (evidence: `src/raspi_cloud_sync_pro/gadget.py`)
- Mass-storage appliance → Durable staging: captures files
- Mass-storage appliance → Storage ownership: guards capture (evidence: `src/raspi_cloud_sync_pro/mass_storage_appliance.py`)
- Mass-storage appliance → Capture admission: checks capacity (evidence: `src/raspi_cloud_sync_pro/mass_storage_appliance.py`)
- Image enrollment → Image policy: validates image (evidence: `src/raspi_cloud_sync_pro/image_enrollment.py`)
- MTP ingestion → Durable staging: publishes batches (evidence: `src/raspi_cloud_sync_pro/mtp_ingest.py`)
- Samba ingestion → Durable staging: stages files (evidence: `src/raspi_cloud_sync_pro/smb_ingest.py`)
- Durable staging → Backup worker: queues batches (evidence: `src/raspi_cloud_sync_pro/staged_worker.py`)
- Backup worker → Backup engine: runs backup (evidence: `src/raspi_cloud_sync_pro/staged_worker.py`)
- Backup engine → Backup history: records status (evidence: `src/raspi_cloud_sync_pro/engine.py`)
- Backup worker → Wi-Fi policy: checks connectivity (evidence: `src/raspi_cloud_sync_pro/staged_worker.py`)
- Backup worker → Google upload dispatch: dispatches uploads
- Google upload dispatch → Google destination: uses destination (evidence: `src/raspi_cloud_sync_pro/google_upload_dispatcher.py`)
- Google destination → Google Drive: uploads and verifies
- Google setup broker → Google destination: prepares destination (evidence: `src/raspi_cloud_sync_pro/google_broker.py`)
- Owner or viewer → Dashboard: browses files
- Dashboard → Backup history: shows backup history
- Dashboard → Google setup broker: requests setup
