# pavansaipendry/quickdrop architecture

> Architecture diagram of the GitHub repository pavansaipendry/quickdrop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pavansaipendry/quickdrop
- Repository: https://github.com/pavansaipendry/quickdrop

## Overview

**QuickDrop** is a **single-host, script-driven utility** to move files between **macOS** and **Android** using **two independent transfer paths**:

1) **WiFi transfer**: a local **Python web app** (Flask) running on the Mac, served by **Waitress**, accessed via the Android phone’s **mobile browser** over LAN. Files land in / are served from a **shared folder** on the Mac (per README: `~/Downloads/PhoneTransfer`). Includes **QR code** generation for easy URL entry and **chunked uploads** for large files.

2) **USB transfer**: not a server app—this is the user running **ADB CLI** commands (`adb push/pull`) on the Mac to talk to the phone over USB (ADB uses `adbd` on the phone).

##### What the repo structure implies architecturally
From the file tree:

- `file_transfer.py` → the **WiFi mode entrypoint**. This is the core runtime artifact: “run a tiny web server on your Mac”.
- `quicksend.py` → likely a **helper CLI/wrapper** script (often used to simplify sending/pulling via ADB or managing the shared folder); even if it’s optional, include it as a “CLI helper” component if it participates in flows.
- `requirements.txt` → confirms Python deps (README lists: `flask`, `qrcode`, `Pillow`, `waitress`).

This is not microservices / not client-server across the internet. It’s **local-only** with the Mac acting as the server for WiFi mode.

##### Flask App (QuickDrop WiFi server)
- Routes/API for:
- **Upload** (chunked for large files per README)
- **List files** in shared directory
- **Download file**
- Any “chunk reassembly” logic as a sub-component (even if it’s just functions)
##### QR Code Generator
- `qrcode` + `Pillow` (PIL) used to render the QR shown in terminal (per README output)
##### Shared Folder on Mac filesystem
- `~/Downloads/PhoneTransfer` (source of truth for files)
##### Android Client
- **Mobile Browser UI**
- Drag/drop / file picker upload
- Downloads via HTTP

- Android Browser → Flask: `HTTP GET /` (loads UI)
- Flask → Shared Folder: “write chunk”, “assemble file”, “save final file”
- Android Browser → Flask: `HTTP GET /files` (or server-side rendered list)
- Android Browser → Flask: `HTTP GET /download/<filename>` (streams file)
- Flask → QR Code Generator: “encode URL → bitmap”
- Flask → Console/Terminal: “prints URL + QR” (this is part of UX; worth showing as an output)

**Important architecture notes to annotate**
- **Local network scope**: binds to LAN interface (IP shown like `http://192.168.x.x:5000`)
- **Chunking**: indicate “chunks stored temporarily; reassembled into final file”
- **Performance expectation**: show “WiFi 5–30 MB/s typical, can be higher on 5GHz” (optional annotation)

Goal: accurately show it’s *not* part of the Flask app, but still part of the QuickDrop solution.

**Components**
- **Mac Terminal / User**
- **ADB CLI** (`adb`) installed via Homebrew
- **USB Transport**
- **Android `adbd` daemon**
- **Android filesystem** (paths like `/sdcard/Download/`, `/sdcard/DCIM/Camera/`)

- User → ADB CLI: `adb push local -> /sdcard/...`
- User → ADB CLI: `adb pull /sdcard/... -> local`
- ADB CLI ⇄ Android `adbd`: “ADB protocol over USB”
- `adbd` → Android FS: read/write

“requires Developer Options + USB debugging + authorization”.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =======================
%% System Context (Top)
%% =======================
subgraph CTX["System Context (QuickDrop: local-only; two independent modes)"]
  direction TB

  User["User"]:::actor

  subgraph MACCTX["Mac (QuickDrop Host)"]
    direction TB
    MacTerminal["Terminal / Shell"]:::client
    MacHost["macOS Host"]:::boundary
  end

  subgraph ANDCTX["Android Phone"]
    direction TB
    AndroidBrowser["Mobile Browser"]:::client
    AndroidDevice["Android Device"]:::boundary
    AndroidFS[("Android Filesystem\n(/sdcard/...)")]:::storage
  end

  subgraph NET["Local Network"]
    direction TB
    Router["WiFi Router / AP\n(context)"]:::network
    LAN["Same WiFi LAN\n(no cloud)"]:::network
  end

  subgraph USBCTX["USB Link"]
    direction TB
    USBCable["USB Cable / Transport"]:::network
  end

  MacQuickDropServer["QuickDrop WiFi Server\n(Flask via Waitress)"]:::service
  ADBToolchain["ADB Toolchain\n(adb CLI on Mac)"]:::service
  AndroidAdbd["adbd daemon\n(on Android)"]:::service

  User -.->|"runs Commands"| MacTerminal
  AndroidBrowser -->|"HTTP over LAN"| MacQuickDropServer
  MacTerminal -->|"adb push/pull"| ADBToolchain
  ADBToolchain <-->|"ADB protocol over USB"| USBCable
  USBCable <-->|"ADB transport"| AndroidAdbd

  AndroidAdbd -->|"read/write"| AndroidFS
end

%% =======================
%% WiFi Mode (Bottom-Left)
%% =======================
subgraph WIFI["WiFi Mode (LAN HTTP): Python web app on Mac"]
  direction TB

  subgraph MACWIFI["Mac Runtime"]
    direction TB
    UserWifi["User (Terminal)"]:::actor
    PythonRuntime["Python 3 Runtime"]:::runtime
    Waitress["Waitress WSGI Server"]:::service
    FlaskApp["Flask App\n(file_transfer.py)"]:::service
    QrGen["QR Code Generator\n(qrcode + Pillow)"]:::lib
    SharedFolder[("Shared Folder\n~/Downloads/PhoneTransfer")]:::storage
    ConsoleOut["Console Output\n(URL + QR shown)"]:::client

    UserWifi -.->|"runs: python3 file_transfer.py"| PythonRuntime
    PythonRuntime -->|"starts"| Waitress
    Waitress -->|"serves WSGI"| FlaskApp

    FlaskApp -->|"encode URL -> bitmap"| QrGen
    FlaskApp -->|"prints URL + QR"| ConsoleOut

    FlaskApp -->|"write chunk(s)"| SharedFolder
    FlaskApp -->|"assemble file"| SharedFolder
    FlaskApp -->|"list/read file"| SharedFolder
  end

  subgraph ANDWIFI["Android Client"]
    direction TB
    BrowserUI["Mobile Browser UI\n(file picker / drag-drop)"]:::client
    AndroidDownloads[("Android Storage\n(Downloads/...)")]:::storage

    BrowserUI -->|"saves downloaded file"| AndroidDownloads
  end

  subgraph LANWIFI["LAN Transport"]
    direction TB
    LANHttp["HTTP over WiFi LAN\n(trusted network only; no auth)"]:::network
  end

  BrowserUI -->|"HTTP GET / (load UI)"| FlaskApp
  BrowserUI -->|"HTTP POST /upload (chunked upload; e.g., 10MB parts)"| FlaskApp
  BrowserUI -->|"HTTP GET /files (list)"| FlaskApp
  BrowserUI -->|"HTTP GET /download/<filename> (stream)"| FlaskApp

  BrowserUI -->|"uses URL from QR/printed IP"| LANHttp
  LANHttp -->|"routes to Mac LAN IP\n(e.g., http://192.168.x.x:5000)"| FlaskApp
end

%% =======================
%% USB Mode (Bottom-Right)
%% =======================
subgraph USBMODE["USB Mode (ADB): CLI-driven, not part of Flask app"]
  direction TB

  subgraph MACUSB["Mac (User + ADB CLI)"]
    direction TB
    UserUsb["User (Terminal)"]:::actor
    AdbCli["adb CLI\n(Homebrew install)"]:::service
    LocalShared[("Local Folder\n~/Downloads/PhoneTransfer")]:::storage

    UserUsb -.->|"runs: adb push/pull"| AdbCli
    AdbCli -->|"read/write local files"| LocalShared
  end

  subgraph USBLINK["USB Transport"]
    direction TB
    UsbTransport["USB Cable / Transport"]:::network
  end

  subgraph ANDUSB["Android (USB debugging)"]
    direction TB
    DevOpts["Developer Options\nUSB debugging + authorize host"]:::note
    Adbd["adbd daemon"]:::service
    PhoneFS[("Android Filesystem\n(/sdcard/Download/, /sdcard/DCIM/Camera/)")]:::storage

    DevOpts -.->|"enables"| Adbd
    Adbd -->|"read/write"| PhoneFS
  end

  AdbCli <-->|"ADB protocol over USB"| UsbTransport
  UsbTransport <-->|"ADB transport"| Adbd

  AdbCli -->|"adb push: local -> /sdcard/..."| PhoneFS
  AdbCli -->|"adb pull: /sdcard/... -> local"| LocalShared
end

%% =======================
%% Cross-links (clarify separation)
%% =======================
MacQuickDropServer -.->|"WiFi mode runtime component"| FlaskApp
ADBToolchain -.->|"USB mode toolchain component"| AdbCli
AndroidAdbd -.->|"USB endpoint on phone"| Adbd

%% Dummy node to attach HOW_IT_WORKS.md click without clutter
HOW["Internal Notes\n(HOW_IT_WORKS)"]:::doc
HOW -.->|"implementation notes"| FlaskApp

%% =======================
%% Click Events (from component_mapping)
%% =======================
click MacQuickDropServer "https://github.com/pavansaipendry/quickdrop/blob/main/file_transfer.py"
click FlaskApp "https://github.com/pavansaipendry/quickdrop/blob/main/file_transfer.py"
click Waitress "https://github.com/pavansaipendry/quickdrop/blob/main/file_transfer.py"
click QrGen "https://github.com/pavansaipendry/quickdrop/blob/main/file_transfer.py"
click AdbCli "https://github.com/pavansaipendry/quickdrop/blob/main/quicksend.py"
click ADBToolchain "https://github.com/pavansaipendry/quickdrop/blob/main/quicksend.py"
click PythonRuntime "https://github.com/pavansaipendry/quickdrop/blob/main/requirements.txt"
click DevOpts "https://github.com/pavansaipendry/quickdrop/blob/main/README.md"
click CTX "https://github.com/pavansaipendry/quickdrop/blob/main/README.md"
click WIFI "https://github.com/pavansaipendry/quickdrop/blob/main/README.md"
click USBMODE "https://github.com/pavansaipendry/quickdrop/blob/main/README.md"
click ConsoleOut "https://github.com/pavansaipendry/quickdrop/blob/main/README.md"
click LANHttp "https://github.com/pavansaipendry/quickdrop/blob/main/README.md"
click MACWIFI "https://github.com/pavansaipendry/quickdrop/blob/main/file_transfer.py"
click MACUSB "https://github.com/pavansaipendry/quickdrop/blob/main/quicksend.py"
click SharedFolder "https://github.com/pavansaipendry/quickdrop/blob/main/README.md"
click HOW "https://github.com/pavansaipendry/quickdrop/blob/main/HOW_IT_WORKS.md"

%% =======================
%% Styles
%% =======================
classDef actor fill:#FFF3BF,stroke:#8A6D3B,stroke-width:1px,color:#3B2F1C;
classDef boundary fill:#E9ECEF,stroke:#6C757D,stroke-width:1px,color:#212529;
classDef service fill:#D0EBFF,stroke:#1C7ED6,stroke-width:1.2px,color:#0B2E4A;
classDef runtime fill:#C5F6FA,stroke:#1098AD,stroke-width:1.2px,color:#053B43;
classDef client fill:#E7F5FF,stroke:#228BE6,stroke-width:1px,color:#0B2E4A;
classDef storage fill:#E6FCF5,stroke:#12B886,stroke-width:1.2px,color:#063D2E;
classDef network fill:#F1F3F5,stroke:#868E96,stroke-width:1px,color:#212529;
classDef lib fill:#E5DBFF,stroke:#7950F2,stroke-width:1px,color:#2B155F;
classDef note fill:#FFE3E3,stroke:#FA5252,stroke-width:1px,color:#4A0B0B;
classDef doc fill:#FFF0F6,stroke:#D6336C,stroke-width:1px,color:#4A1030;

class User,UserWifi,UserUsb actor
class MacHost,AndroidDevice boundary
class MacQuickDropServer,Waitress,FlaskApp,ADBToolchain,AdbCli,AndroidAdbd,Adbd service
class PythonRuntime runtime
class MacTerminal,AndroidBrowser,BrowserUI,ConsoleOut client
class SharedFolder,LocalShared,AndroidFS,PhoneFS,AndroidDownloads storage
class Router,LAN,USBCable,UsbTransport,LANHttp network
class QrGen lib
class DevOpts note
class HOW doc
```
