# samucamg/nebulaftp architecture

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

- Interactive diagram: https://gitdiagram.com/samucamg/nebulaftp
- Repository: https://github.com/samucamg/nebulaftp

## Overview

Nebula FTP exposes Telegram-backed files through FTP and SFTP, with a web panel for user and folder permissions. The main workflow is client authentication and file operations through a protocol server, PathIO metadata/local staging, background chunk uploads to Telegram, and on-demand part reads for downloads. SQLite is the default metadata store; MongoDB is an alternative. The README documents staging workers, cleanup, streaming, and metrics, but their exact wiring is only partly visible in the sampled source, so uncertain links are omitted.

Main entry points: [`ftp/pathio.py`](https://github.com/samucamg/nebulaftp/blob/master/ftp/pathio.py) (Virtual filesystem), [`ftp/sqlite_db.py`](https://github.com/samucamg/nebulaftp/blob/master/ftp/sqlite_db.py) (Metadata store), [`main.py`](https://github.com/samucamg/nebulaftp/blob/master/main.py) (Upload workers), [`ftp/server.py`](https://github.com/samucamg/nebulaftp/blob/master/ftp/server.py) (FTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Client access"]
  node_ftp_server["FTP server<br/>[server.py]"]
  node_sftp_server["SFTP server<br/>[sftp.py]"]
  node_user_access["User authentication<br/>[sqlite_db.py]"]
end

subgraph group_storage["File storage"]
  node_pathio["Virtual filesystem<br/>[pathio.py]"]
  node_sqlite_pathio["SQLite filesystem<br/>[sqlite_db.py]"]
  node_sqlite_adapter["SQLite adapter<br/>[sqlite_adapter.py]"]
  node_metadata[("Metadata store<br/>[sqlite_db.py]")]
  node_staging[("Local staging<br/>[main.py]")]
  node_telegram[("Telegram channel")]
  node_telegram_reader["Telegram part reader<br/>[tg.py]"]
  node_mongodb[("MongoDB backend<br/>[pathio.py]")]
end

subgraph group_admin["Administration"]
  node_web_panel["Admin panel<br/>[app.py]"]
end

subgraph group_operations["Runtime operations"]
  node_watcher["Staging watcher<br/>[main.py]"]
  node_upload_queue["Upload queue<br/>[common.py]"]
  node_upload_workers["Upload workers<br/>[main.py]"]
  node_cleanup["Staging cleanup<br/>[main.py]"]
  node_metrics["Runtime metrics<br/>[main.py]"]
end

node_ftp_client(("FTP client"))
node_sftp_client(("SFTP client"))
node_web_admin(("Web administrator"))

node_ftp_client -->|"issues FTP commands"| node_ftp_server
node_sftp_client -->|"issues SFTP requests"| node_sftp_server
node_web_admin -->|"manages accounts"| node_web_panel
node_ftp_server -->|"authenticates users"| node_user_access
node_sftp_server -->|"authenticates users"| node_user_access
node_ftp_server -->|"performs file operations"| node_pathio
node_sftp_server -->|"performs file operations"| node_pathio
node_pathio -.->|"uses SQLite filesystem"| node_sqlite_pathio
node_sqlite_pathio -->|"reads and writes"| node_metadata
node_pathio -.->|"uses MongoDB backend"| node_mongodb
node_web_panel -->|"manages users"| node_metadata
node_watcher -->|"scans files"| node_staging
node_watcher -->|"registers files"| node_metadata
node_watcher -->|"enqueues uploads"| node_upload_queue
node_pathio -->|"enqueues completed writes"| node_upload_queue
node_upload_workers -->|"dequeues uploads"| node_upload_queue
node_upload_workers -->|"uploads file parts"| node_telegram
node_upload_workers -->|"stores part metadata"| node_metadata
node_pathio -->|"requests missing local data"| node_telegram_reader
node_telegram_reader -->|"reads file parts"| node_telegram
node_pathio -->|"loads file parts"| node_metadata
node_cleanup -->|"removes stale files"| node_staging
node_metrics -.->|"reports activity"| node_upload_workers

click node_ftp_server "https://github.com/samucamg/nebulaftp/blob/master/ftp/server.py"
click node_sftp_server "https://github.com/samucamg/nebulaftp/blob/master/ftp/sftp.py"
click node_web_panel "https://github.com/samucamg/nebulaftp/blob/master/web/app.py"
click node_user_access "https://github.com/samucamg/nebulaftp/blob/master/ftp/sqlite_db.py"
click node_pathio "https://github.com/samucamg/nebulaftp/blob/master/ftp/pathio.py"
click node_sqlite_pathio "https://github.com/samucamg/nebulaftp/blob/master/ftp/sqlite_db.py"
click node_sqlite_adapter "https://github.com/samucamg/nebulaftp/blob/master/ftp/sqlite_adapter.py"
click node_metadata "https://github.com/samucamg/nebulaftp/blob/master/ftp/sqlite_db.py"
click node_staging "https://github.com/samucamg/nebulaftp/blob/master/main.py"
click node_watcher "https://github.com/samucamg/nebulaftp/blob/master/main.py"
click node_upload_queue "https://github.com/samucamg/nebulaftp/blob/master/ftp/common.py"
click node_upload_workers "https://github.com/samucamg/nebulaftp/blob/master/main.py"
click node_telegram_reader "https://github.com/samucamg/nebulaftp/blob/master/ftp/tg.py"
click node_cleanup "https://github.com/samucamg/nebulaftp/blob/master/main.py"
click node_metrics "https://github.com/samucamg/nebulaftp/blob/master/main.py"
click node_mongodb "https://github.com/samucamg/nebulaftp/blob/master/ftp/pathio.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_ftp_server,node_sftp_server,node_user_access,node_ftp_client,node_sftp_client toneBlue
class node_pathio,node_sqlite_pathio,node_sqlite_adapter,node_metadata,node_staging,node_telegram,node_telegram_reader,node_mongodb toneAmber
class node_web_panel toneMint
class node_watcher,node_upload_queue,node_upload_workers,node_cleanup,node_metrics toneRose
class node_web_admin toneIndigo
```

## Components

### Client access

- [FTP server](https://github.com/samucamg/nebulaftp/blob/master/ftp/server.py): `ftp/server.py`
- [SFTP server](https://github.com/samucamg/nebulaftp/blob/master/ftp/sftp.py): `ftp/sftp.py`
- [User authentication](https://github.com/samucamg/nebulaftp/blob/master/ftp/sqlite_db.py): `ftp/sqlite_db.py`

### File storage

- [Virtual filesystem](https://github.com/samucamg/nebulaftp/blob/master/ftp/pathio.py): `ftp/pathio.py`
- [SQLite filesystem](https://github.com/samucamg/nebulaftp/blob/master/ftp/sqlite_db.py): `ftp/sqlite_db.py`
- [SQLite adapter](https://github.com/samucamg/nebulaftp/blob/master/ftp/sqlite_adapter.py): `ftp/sqlite_adapter.py`
- [Metadata store](https://github.com/samucamg/nebulaftp/blob/master/ftp/sqlite_db.py): `ftp/sqlite_db.py`
- [Local staging](https://github.com/samucamg/nebulaftp/blob/master/main.py): `main.py`
- **Telegram channel**
- [Telegram part reader](https://github.com/samucamg/nebulaftp/blob/master/ftp/tg.py): `ftp/tg.py`
- [MongoDB backend](https://github.com/samucamg/nebulaftp/blob/master/ftp/pathio.py): `ftp/pathio.py`

### Administration

- [Admin panel](https://github.com/samucamg/nebulaftp/blob/master/web/app.py): `web/app.py`

### Runtime operations

- [Staging watcher](https://github.com/samucamg/nebulaftp/blob/master/main.py): `main.py`
- [Upload queue](https://github.com/samucamg/nebulaftp/blob/master/ftp/common.py): `ftp/common.py`
- [Upload workers](https://github.com/samucamg/nebulaftp/blob/master/main.py): `main.py`
- [Staging cleanup](https://github.com/samucamg/nebulaftp/blob/master/main.py): `main.py`
- [Runtime metrics](https://github.com/samucamg/nebulaftp/blob/master/main.py): `main.py`

### Other components

- **FTP client**
- **SFTP client**
- **Web administrator**

## Connections

- FTP client → FTP server: issues FTP commands
- SFTP client → SFTP server: issues SFTP requests
- Web administrator → Admin panel: manages accounts
- FTP server → User authentication: authenticates users
- SFTP server → User authentication: authenticates users
- FTP server → Virtual filesystem: performs file operations
- SFTP server → Virtual filesystem: performs file operations
- Virtual filesystem → SQLite filesystem: uses SQLite filesystem
- SQLite filesystem → Metadata store: reads and writes
- Virtual filesystem → MongoDB backend: uses MongoDB backend
- Admin panel → Metadata store: manages users
- Staging watcher → Local staging: scans files
- Staging watcher → Metadata store: registers files
- Staging watcher → Upload queue: enqueues uploads
- Virtual filesystem → Upload queue: enqueues completed writes
- Upload workers → Upload queue: dequeues uploads
- Upload workers → Telegram channel: uploads file parts
- Upload workers → Metadata store: stores part metadata
- Virtual filesystem → Telegram part reader: requests missing local data
- Telegram part reader → Telegram channel: reads file parts
- Virtual filesystem → Metadata store: loads file parts
- Staging cleanup → Local staging: removes stale files
- Runtime metrics → Upload workers: reports activity