# swanand58/cloudless architecture

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

- Interactive diagram: https://gitdiagram.com/swanand58/cloudless
- Repository: https://github.com/swanand58/cloudless

## Overview

Cloudless is a self-hosted, invite-only sharing app for two-person rooms. A user registers or signs in, creates or joins a room, verifies the other person’s safety number, then sends encrypted messages or files for later retrieval. The browser encrypts content before upload; the backend manages accounts, room membership, encrypted message and chunk storage, and expiry cleanup. The README documents the browser-to-server boundary and product workflow; source excerpts support backend routing and lifecycle edges, while some frontend wiring is not shown.

Main entry points: [`backend/app/main.py`](https://github.com/swanand58/cloudless/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/database.py`](https://github.com/swanand58/cloudless/blob/main/backend/app/database.py) (SQLite database), [`backend/app/routers/transfer.py`](https://github.com/swanand58/cloudless/blob/main/backend/app/routers/transfer.py) (File transfers), [`backend/app/services/cleanup.py`](https://github.com/swanand58/cloudless/blob/main/backend/app/services/cleanup.py) (Expiry cleanup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser experience"]
  node_account_pages["Account pages<br/>[page.tsx]"]
  node_registration["Invite registration<br/>[page.tsx]"]
  node_room_list["Room list<br/>[page.tsx]"]
  node_room_page["Room view<br/>[page.tsx]"]
  node_chat["Encrypted chat<br/>[ChatWindow.tsx]"]
  node_file_view["File previews<br/>[FileBubble.tsx]"]
  node_safety["Identity verification<br/>[VerifyIdentity.tsx]"]
  node_browser_crypto["Browser encryption<br/>[filecrypt.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Backend workflows"]
  node_app_entry["FastAPI application<br/>[main.py]"]
  node_auth_routes["Auth and invites<br/>[auth.py]"]
  node_room_routes["Room management<br/>[rooms.py]"]
  node_transfer_routes["File transfers<br/>[transfer.py]"]
  node_websocket["Live messaging<br/>[websocket.py]"]
end

subgraph group_data["Persistence"]
  node_database[("SQLite database<br/>[database.py]")]
  node_user_model["Users and invites<br/>[user.py]"]
  node_room_model["Rooms and members<br/>[room.py]"]
  node_message_model["Encrypted messages<br/>[message.py]"]
  node_transfer_model["Transfer metadata<br/>[transfer.py]"]
end

subgraph group_lifecycle["Security and lifecycle"]
  node_auth_service["Authentication service<br/>[auth.py]"]
  node_cleanup["Expiry cleanup<br/>[cleanup.py]"]
  node_security["Request security<br/>[security.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_person(("Room participants"))

node_person -->|"signs in"| node_account_pages
node_person -->|"uses invite"| node_registration
node_person -->|"creates or joins"| node_room_list
node_person -->|"opens room"| node_room_page
node_room_page -.->|"shows chat"| node_chat
node_chat -->|"renders attachments"| node_file_view
node_person -->|"compares fingerprints"| node_safety
node_person -->|"encrypts content"| node_browser_crypto
node_api_client -->|"calls API"| node_app_entry
node_app_entry -->|"registers routes"| node_auth_routes
node_app_entry -->|"registers routes"| node_room_routes
node_app_entry -->|"registers routes"| node_transfer_routes
node_app_entry -->|"registers route"| node_websocket
node_app_entry -->|"installs middleware"| node_security
node_app_entry -->|"starts service"| node_cleanup
node_auth_routes -->|"delegates auth"| node_auth_service
node_auth_routes -->|"reads and writes"| node_user_model
node_room_routes -->|"reads and writes"| node_room_model
node_room_routes -->|"checks membership"| node_user_model
node_transfer_routes -->|"checks membership"| node_room_routes
node_transfer_routes -->|"reads and writes"| node_transfer_model
node_websocket -->|"checks room"| node_room_model
node_websocket -->|"stores messages"| node_message_model
node_cleanup -->|"expires rooms"| node_room_model
node_cleanup -->|"deletes messages"| node_message_model
node_cleanup -->|"deletes transfers"| node_transfer_model
node_auth_service -->|"loads accounts"| node_user_model
node_database -->|"uses database URL"| node_settings
node_user_model -->|"maps tables"| node_database
node_room_model -->|"maps tables"| node_database
node_message_model -->|"maps tables"| node_database
node_transfer_model -->|"maps tables"| node_database
node_transfer_routes -->|"transfers ciphertext"| node_browser_crypto

click node_account_pages "https://github.com/swanand58/cloudless/blob/main/frontend/src/app/login/page.tsx"
click node_registration "https://github.com/swanand58/cloudless/blob/main/frontend/src/app/register/page.tsx"
click node_room_list "https://github.com/swanand58/cloudless/blob/main/frontend/src/app/page.tsx"
click node_room_page "https://github.com/swanand58/cloudless/blob/main/frontend/src/app/room/%5Bid%5D/page.tsx"
click node_chat "https://github.com/swanand58/cloudless/blob/main/frontend/src/components/ChatWindow.tsx"
click node_file_view "https://github.com/swanand58/cloudless/blob/main/frontend/src/components/FileBubble.tsx"
click node_safety "https://github.com/swanand58/cloudless/blob/main/frontend/src/components/room/VerifyIdentity.tsx"
click node_browser_crypto "https://github.com/swanand58/cloudless/blob/main/frontend/src/lib/filecrypt.ts"
click node_api_client "https://github.com/swanand58/cloudless/blob/main/frontend/src/lib/api.ts"
click node_app_entry "https://github.com/swanand58/cloudless/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/swanand58/cloudless/blob/main/backend/app/routers/auth.py"
click node_auth_service "https://github.com/swanand58/cloudless/blob/main/backend/app/services/auth.py"
click node_room_routes "https://github.com/swanand58/cloudless/blob/main/backend/app/routers/rooms.py"
click node_transfer_routes "https://github.com/swanand58/cloudless/blob/main/backend/app/routers/transfer.py"
click node_websocket "https://github.com/swanand58/cloudless/blob/main/backend/app/routers/websocket.py"
click node_cleanup "https://github.com/swanand58/cloudless/blob/main/backend/app/services/cleanup.py"
click node_security "https://github.com/swanand58/cloudless/blob/main/backend/app/middleware/security.py"
click node_database "https://github.com/swanand58/cloudless/blob/main/backend/app/database.py"
click node_user_model "https://github.com/swanand58/cloudless/blob/main/backend/app/models/user.py"
click node_room_model "https://github.com/swanand58/cloudless/blob/main/backend/app/models/room.py"
click node_message_model "https://github.com/swanand58/cloudless/blob/main/backend/app/models/message.py"
click node_transfer_model "https://github.com/swanand58/cloudless/blob/main/backend/app/models/transfer.py"
click node_settings "https://github.com/swanand58/cloudless/blob/main/backend/app/config.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_account_pages,node_registration,node_room_list,node_room_page,node_chat,node_file_view,node_safety,node_browser_crypto,node_api_client toneBlue
class node_app_entry,node_auth_routes,node_room_routes,node_transfer_routes,node_websocket toneAmber
class node_database,node_user_model,node_room_model,node_message_model,node_transfer_model toneMint
class node_auth_service,node_cleanup,node_security,node_settings toneRose
class node_person toneIndigo
```

## Components

### Browser experience

- [Account pages](https://github.com/swanand58/cloudless/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Invite registration](https://github.com/swanand58/cloudless/blob/main/frontend/src/app/register/page.tsx): `frontend/src/app/register/page.tsx`
- [Room list](https://github.com/swanand58/cloudless/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Room view](https://github.com/swanand58/cloudless/blob/main/frontend/src/app/room/%5Bid%5D/page.tsx): `frontend/src/app/room/[id]/page.tsx`
- [Encrypted chat](https://github.com/swanand58/cloudless/blob/main/frontend/src/components/ChatWindow.tsx): `frontend/src/components/ChatWindow.tsx`
- [File previews](https://github.com/swanand58/cloudless/blob/main/frontend/src/components/FileBubble.tsx): `frontend/src/components/FileBubble.tsx`
- [Identity verification](https://github.com/swanand58/cloudless/blob/main/frontend/src/components/room/VerifyIdentity.tsx): `frontend/src/components/room/VerifyIdentity.tsx`
- [Browser encryption](https://github.com/swanand58/cloudless/blob/main/frontend/src/lib/filecrypt.ts): `frontend/src/lib/filecrypt.ts`
- [API client](https://github.com/swanand58/cloudless/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Backend workflows

- [FastAPI application](https://github.com/swanand58/cloudless/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth and invites](https://github.com/swanand58/cloudless/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Room management](https://github.com/swanand58/cloudless/blob/main/backend/app/routers/rooms.py): `backend/app/routers/rooms.py`
- [File transfers](https://github.com/swanand58/cloudless/blob/main/backend/app/routers/transfer.py): `backend/app/routers/transfer.py`
- [Live messaging](https://github.com/swanand58/cloudless/blob/main/backend/app/routers/websocket.py): `backend/app/routers/websocket.py`

### Persistence

- [SQLite database](https://github.com/swanand58/cloudless/blob/main/backend/app/database.py): `backend/app/database.py`
- [Users and invites](https://github.com/swanand58/cloudless/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Rooms and members](https://github.com/swanand58/cloudless/blob/main/backend/app/models/room.py): `backend/app/models/room.py`
- [Encrypted messages](https://github.com/swanand58/cloudless/blob/main/backend/app/models/message.py): `backend/app/models/message.py`
- [Transfer metadata](https://github.com/swanand58/cloudless/blob/main/backend/app/models/transfer.py): `backend/app/models/transfer.py`

### Security and lifecycle

- [Authentication service](https://github.com/swanand58/cloudless/blob/main/backend/app/services/auth.py): `backend/app/services/auth.py`
- [Expiry cleanup](https://github.com/swanand58/cloudless/blob/main/backend/app/services/cleanup.py): `backend/app/services/cleanup.py`
- [Request security](https://github.com/swanand58/cloudless/blob/main/backend/app/middleware/security.py): `backend/app/middleware/security.py`
- [Runtime settings](https://github.com/swanand58/cloudless/blob/main/backend/app/config.py): `backend/app/config.py`

### Other components

- **Room participants**

## Connections

- Room participants → Account pages: signs in (evidence: `README.md`)
- Room participants → Invite registration: uses invite (evidence: `README.md`)
- Room participants → Room list: creates or joins (evidence: `README.md`)
- Room participants → Room view: opens room (evidence: `README.md`)
- Room view → Encrypted chat: shows chat
- Encrypted chat → File previews: renders attachments (evidence: `frontend/src/components/ChatWindow.tsx`)
- Room participants → Identity verification: compares fingerprints (evidence: `README.md`)
- Room participants → Browser encryption: encrypts content (evidence: `README.md`)
- API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Auth and invites: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Room management: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → File transfers: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Live messaging: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Request security: installs middleware (evidence: `backend/app/main.py`)
- FastAPI application → Expiry cleanup: starts service (evidence: `backend/app/main.py`)
- Auth and invites → Authentication service: delegates auth (evidence: `backend/app/routers/auth.py`)
- Auth and invites → Users and invites: reads and writes (evidence: `backend/app/routers/auth.py`)
- Room management → Rooms and members: reads and writes (evidence: `backend/app/routers/rooms.py`)
- Room management → Users and invites: checks membership (evidence: `backend/app/routers/rooms.py`)
- File transfers → Room management: checks membership (evidence: `backend/app/routers/transfer.py`)
- File transfers → Transfer metadata: reads and writes (evidence: `backend/app/routers/transfer.py`)
- Live messaging → Rooms and members: checks room (evidence: `backend/app/routers/websocket.py`)
- Live messaging → Encrypted messages: stores messages (evidence: `backend/app/routers/websocket.py`)
- Expiry cleanup → Rooms and members: expires rooms (evidence: `backend/app/services/cleanup.py`)
- Expiry cleanup → Encrypted messages: deletes messages (evidence: `backend/app/services/cleanup.py`)
- Expiry cleanup → Transfer metadata: deletes transfers (evidence: `backend/app/services/cleanup.py`)
- Authentication service → Users and invites: loads accounts (evidence: `backend/app/services/auth.py`)
- SQLite database → Runtime settings: uses database URL (evidence: `backend/app/database.py`)
- Users and invites → SQLite database: maps tables (evidence: `backend/app/models/user.py`)
- Rooms and members → SQLite database: maps tables (evidence: `backend/app/models/room.py`)
- Encrypted messages → SQLite database: maps tables (evidence: `backend/app/models/message.py`)
- Transfer metadata → SQLite database: maps tables (evidence: `backend/app/models/transfer.py`)
- File transfers → Browser encryption: transfers ciphertext (evidence: `README.md`)
