# ai-platon/teledrop architecture

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

- Interactive diagram: https://gitdiagram.com/ai-platon/teledrop
- Repository: https://github.com/ai-platon/teledrop

## Overview

TeleDrop is a macOS notch drop zone that turns dragged files, images, links, or text into messages or uploads to the user’s Telegram bot. The main workflow runs from drag-and-drop handling through upload state and file preparation to Telegram; setup, settings, notch placement, Coucou awareness, localization, and sound are supporting capabilities. Edges use the provided excerpts, source-index references, or README; unsampled internals are not assumed.

Main entry points: [`Sources/Model.swift`](https://github.com/ai-platon/teledrop/blob/main/Sources/Model.swift) (Send state and progress), [`Sources/Telegram.swift`](https://github.com/ai-platon/teledrop/blob/main/Sources/Telegram.swift) (Bot API client), [`Sources/Setup.swift`](https://github.com/ai-platon/teledrop/blob/main/Sources/Setup.swift) (Bot setup and settings UI), [`Sources/Island.swift`](https://github.com/ai-platon/teledrop/blob/main/Sources/Island.swift) (Drop island and pasteboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Drop Interaction"]
  node_main["App and drag watcher<br/>[main.swift]"]
  node_island["Drop island and pasteboard<br/>[Island.swift]"]
end

subgraph group_delivery["Upload Delivery"]
  node_model["Send state and progress<br/>[Model.swift]"]
  node_packer["Zip and split files<br/>[Telegram.swift]"]
  node_telegram_client["Bot API client<br/>[Telegram.swift]"]
end

subgraph group_configuration["Setup and Preferences"]
  node_setup["Bot setup and settings UI<br/>[Setup.swift]"]
  node_settings[("Credentials and preferences<br/>[Settings.swift]")]
  node_lang["Localization<br/>[Lang.swift]"]
end

subgraph group_experience["Notch Experience"]
  node_layout["Island placement rules<br/>[Layout.swift]"]
  node_coucou_watch["Coucou detection<br/>[Coucou.swift]"]
  node_island_view["Island progress display<br/>[Island.swift]"]
  node_sound["UI sound effects<br/>[Sound.swift]"]
  node_engine["Upload engine sound<br/>[Engine.swift]"]
  node_mascot["Mascot artwork<br/>[Mascot.swift]"]
end

node_user(("Mac user"))
node_telegram{{"Telegram Bot API"}}
node_coucou{{"Coucou"}}
node_macos{{"macOS files and pasteboard"}}

node_user -->|"drops content"| node_island
node_main -->|"hosts drop view"| node_island
node_island -->|"submits content"| node_model
node_model -->|"prepares files"| node_packer
node_model -->|"sends uploads"| node_telegram_client
node_model -->|"sends links"| node_telegram_client
node_telegram_client -->|"calls Bot API"| node_telegram
node_telegram -->|"returns API results"| node_telegram_client
node_model -->|"reads dropped files"| node_macos
node_model -->|"downloads iCloud files"| node_macos
node_user -->|"configures bot"| node_setup
node_setup -->|"checks token and chat"| node_telegram_client
node_setup -->|"updates preferences"| node_settings
node_model -->|"loads bot config"| node_settings
node_settings -->|"selects language"| node_lang
node_main -->|"positions island"| node_layout
node_main -->|"checks Coucou"| node_coucou_watch
node_coucou_watch -->|"reads panel edges"| node_coucou
node_model -->|"drives upload sound"| node_engine
node_island -->|"renders progress"| node_island_view
node_setup -->|"plays UI sounds"| node_sound
node_island_view -.->|"renders mascot"| node_mascot

click node_main "https://github.com/ai-platon/teledrop/blob/main/Sources/main.swift"
click node_island "https://github.com/ai-platon/teledrop/blob/main/Sources/Island.swift"
click node_model "https://github.com/ai-platon/teledrop/blob/main/Sources/Model.swift"
click node_packer "https://github.com/ai-platon/teledrop/blob/main/Sources/Telegram.swift"
click node_telegram_client "https://github.com/ai-platon/teledrop/blob/main/Sources/Telegram.swift"
click node_setup "https://github.com/ai-platon/teledrop/blob/main/Sources/Setup.swift"
click node_settings "https://github.com/ai-platon/teledrop/blob/main/Sources/Settings.swift"
click node_lang "https://github.com/ai-platon/teledrop/blob/main/Sources/Lang.swift"
click node_layout "https://github.com/ai-platon/teledrop/blob/main/Sources/Layout.swift"
click node_coucou_watch "https://github.com/ai-platon/teledrop/blob/main/Sources/Coucou.swift"
click node_island_view "https://github.com/ai-platon/teledrop/blob/main/Sources/Island.swift"
click node_sound "https://github.com/ai-platon/teledrop/blob/main/Sources/Sound.swift"
click node_engine "https://github.com/ai-platon/teledrop/blob/main/Sources/Engine.swift"
click node_mascot "https://github.com/ai-platon/teledrop/blob/main/Sources/Mascot.swift"

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_main,node_island,node_user toneBlue
class node_model,node_packer,node_telegram_client toneAmber
class node_setup,node_settings,node_lang,node_telegram toneMint
class node_layout,node_coucou_watch,node_island_view,node_sound,node_engine,node_mascot toneRose
class node_coucou,node_macos toneIndigo
```

## Components

### Drop Interaction

- [App and drag watcher](https://github.com/ai-platon/teledrop/blob/main/Sources/main.swift): `Sources/main.swift`
- [Drop island and pasteboard](https://github.com/ai-platon/teledrop/blob/main/Sources/Island.swift): `Sources/Island.swift`

### Upload Delivery

- [Send state and progress](https://github.com/ai-platon/teledrop/blob/main/Sources/Model.swift): `Sources/Model.swift`
- [Zip and split files](https://github.com/ai-platon/teledrop/blob/main/Sources/Telegram.swift): `Sources/Telegram.swift`
- [Bot API client](https://github.com/ai-platon/teledrop/blob/main/Sources/Telegram.swift): `Sources/Telegram.swift`

### Setup and Preferences

- [Bot setup and settings UI](https://github.com/ai-platon/teledrop/blob/main/Sources/Setup.swift): `Sources/Setup.swift`
- [Credentials and preferences](https://github.com/ai-platon/teledrop/blob/main/Sources/Settings.swift): `Sources/Settings.swift`
- [Localization](https://github.com/ai-platon/teledrop/blob/main/Sources/Lang.swift): `Sources/Lang.swift`

### Notch Experience

- [Island placement rules](https://github.com/ai-platon/teledrop/blob/main/Sources/Layout.swift): `Sources/Layout.swift`
- [Coucou detection](https://github.com/ai-platon/teledrop/blob/main/Sources/Coucou.swift): `Sources/Coucou.swift`
- [Island progress display](https://github.com/ai-platon/teledrop/blob/main/Sources/Island.swift): `Sources/Island.swift`
- [UI sound effects](https://github.com/ai-platon/teledrop/blob/main/Sources/Sound.swift): `Sources/Sound.swift`
- [Upload engine sound](https://github.com/ai-platon/teledrop/blob/main/Sources/Engine.swift): `Sources/Engine.swift`
- [Mascot artwork](https://github.com/ai-platon/teledrop/blob/main/Sources/Mascot.swift): `Sources/Mascot.swift`

### Other components

- **Mac user**
- **Telegram Bot API**
- **Coucou**
- **macOS files and pasteboard**

## Connections

- Mac user → Drop island and pasteboard: drops content (evidence: `README.md`)
- App and drag watcher → Drop island and pasteboard: hosts drop view (evidence: `Sources/main.swift`)
- Drop island and pasteboard → Send state and progress: submits content (evidence: `Sources/Island.swift`)
- Send state and progress → Zip and split files: prepares files (evidence: `Sources/Model.swift`)
- Send state and progress → Bot API client: sends uploads (evidence: `Sources/Model.swift`)
- Send state and progress → Bot API client: sends links (evidence: `Sources/Model.swift`)
- Bot API client → Telegram Bot API: calls Bot API (evidence: `Sources/Telegram.swift`)
- Telegram Bot API → Bot API client: returns API results (evidence: `Sources/Telegram.swift`)
- Send state and progress → macOS files and pasteboard: reads dropped files (evidence: `README.md`)
- Send state and progress → macOS files and pasteboard: downloads iCloud files (evidence: `README.md`)
- Mac user → Bot setup and settings UI: configures bot (evidence: `README.md`)
- Bot setup and settings UI → Bot API client: checks token and chat (evidence: `Sources/Setup.swift`)
- Bot setup and settings UI → Credentials and preferences: updates preferences (evidence: `Sources/Setup.swift`)
- Send state and progress → Credentials and preferences: loads bot config (evidence: `Sources/Model.swift`)
- Credentials and preferences → Localization: selects language (evidence: `Sources/Settings.swift`)
- App and drag watcher → Island placement rules: positions island (evidence: `Sources/main.swift`)
- App and drag watcher → Coucou detection: checks Coucou (evidence: `Sources/main.swift`)
- Coucou detection → Coucou: reads panel edges (evidence: `Sources/Coucou.swift`)
- Send state and progress → Upload engine sound: drives upload sound (evidence: `Sources/Model.swift`)
- Drop island and pasteboard → Island progress display: renders progress (evidence: `Sources/Island.swift`)
- Bot setup and settings UI → UI sound effects: plays UI sounds (evidence: `Sources/Setup.swift`)
- Island progress display → Mascot artwork: renders mascot
