# timvisee/send architecture

> Architecture diagram of the GitHub repository timvisee/send, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timvisee/send
- Repository: https://github.com/timvisee/send

## Overview

##### Project type and purpose
- This is a full-stack, multi-client, encrypted file‐sharing platform (a community-maintained fork of Mozilla Send).
- It provides:
- A single-page Web client (in “app/” + “public/”)
- A Node.js HTTP/WebSocket server (“server/”)
- Mobile clients: Android (“android/”) and iOS (“ios/”)
- Optional CLI compatibility via “ffsend”
- Pluggable storage backends (local FS, S3, GCS, Redis)

##### File structure
- Top-level separation:
- “app/” – front-end application code (JS, CSS, UI components)
- “public/” – static assets & i18n resource bundles
- “server/” – Node.js micro-service, with routes, middleware, storage adapters
- “android/” & “ios/” – native mobile wrappers embedding the web client and platform code
- “common/” – shared scripts for asset mapping
- “build/”, “scripts/” – build/deploy tooling
- “test/” – unit, integration, end-to-end tests
- Docker, CI/CD configs for containerization & pipelines

##### Extract architecture hints from README
- Server is configurable via environment variables; supports Redis for rate-limiting, S3/GCS/FS for storage, FxA for auth.
- Web client is a PWA (with ServiceWorker, QR generation, streaming encryption via WebCrypto, zip.js).
- Android/iOS clients launch a WebView pointing at the same server endpoints.

##### Main components
a. Clients
- Web SPA (browser)
- ServiceWorker & Cache
- Crypto module (WebCrypto + password)
- UI layers (routes.js, various UI/*.js)
- Android App (WebView + native launcher)
- iOS App (WebView + Action Extension)
b. API Gateway / Load Balancer
- Directs HTTPS traffic to server instances (Docker containers)
c. Node.js Server
- Express (middleware/auth/language/limiter)
- Routes (upload, download, metadata, ws)
- Business logic (encryption metadata, file‐chunk streaming)
- Logging & experiments modules
d. Storage Layer
- Pluggable adapters (“server/storage/”):
- FS (local disk)
- S3 / S3-compatible
- GCS
- Redis (for ephemeral state or sessions)
e. External Services
- Redis cluster (rate limiting, state)
- AWS S3 / GCS buckets
- FxA Auth service (OAuth)
f. CDN (optional)
- Hosts static assets, locales, service worker, webmanifest

##### Relationships & interactions
- Browser → HTTPS → Load Balancer → Node.js Server
- Server ↔ Storage adapters for file chunks & metadata
- Server ↔ Redis for limits & ephemeral data
- Server ↔ FxA for user authentication
- Web client ↔ WebSocket for real-time upload/download progress
- Android/iOS → embed WebView → same HTTPS API endpoints

##### Architectural patterns & design principles
- Layered architecture: UI → API layer → storage adapters
- Pluggable storage via strategy pattern in “server/storage/index.js”
- Middleware pipeline in Express for auth, i18n, throttling
- SPA + Service Worker for offline/fallback & progressive enhancement
- CI/CD via Docker, GitLab CI, CircleCI for tests & deployments

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client Tier" 
        direction TB
        WebSPA["Web SPA"]:::client
        AndroidApp["Android App (WebView)"]:::client
        iOSApp["iOS App (WebView)"]:::client
        CLI["CLI (ffsend)"]:::client
    end

    %% Web SPA internals
    subgraph "Web SPA Components"
        direction TB
        SW["ServiceWorker"]:::client
        Routing["Client Routing\n(routes.js)"]:::client
        Streams["Crypto & Streaming\n(streams.js, zip.js)"]:::client
        UI["UI Components\n(ui/)"]:::client
    end

    PublicAssets["Static Assets & Localization\n(public/)"]:::client

    %% API Tier
    APIGW["API Gateway / Load Balancer"]:::app

    %% Application Tier
    subgraph "Application Tier"
        direction TB
        ExpressAPI["Express API & WS"]:::app
        subgraph "Middleware Pipeline"
            AuthMW["auth.js"]:::app
            LangMW["language.js"]:::app
            RateLimit["limiter.js"]:::app
        end
        subgraph "API Routes"
            UploadRoute["upload.js"]:::app
            DownloadRoute["download.js"]:::app
            MetadataRoute["metadata.js"]:::app
            WSRoute["ws.js"]:::app
        end
        subgraph "Business Logic"
            LogMod["log.js"]:::app
            FxaMod["fxa.js"]:::app
            StateMod["state.js"]:::app
            ConfigMod["config.js"]:::app
        end
        StorageInterface["Storage Interface\n(index.js)"]:::app
    end

    %% Data Tier
    subgraph "Storage Adapters" 
        direction TB
        FSAdapter["FS Adapter\n(fs.js)"]:::storage
        S3Adapter["S3 Adapter\n(s3.js)"]:::storage
        GCSAdapter["GCS Adapter\n(gcs.js)"]:::storage
        RedisAdapter["Redis Adapter\n(redis.js)"]:::storage
    end

    %% External Services
    RedisCluster["Redis Cluster"]:::external
    S3Bucket["S3 Bucket"]:::external
    GCSBucket["GCS Bucket"]:::external
    FxaAuth["FxA Auth Service"]:::external
    CDN["CDN"]:::external

    %% Connections
    WebSPA -->|HTTPS| APIGW
    AndroidApp -->|HTTPS| APIGW
    iOSApp -->|HTTPS| APIGW
    CLI -->|HTTPS| APIGW

    APIGW -->|forwards| ExpressAPI

    ExpressAPI -->|uses| AuthMW
    ExpressAPI -->|uses| LangMW
    ExpressAPI -->|uses| RateLimit

    ExpressAPI -->|handles| UploadRoute
    ExpressAPI -->|handles| DownloadRoute
    ExpressAPI -->|handles| MetadataRoute
    ExpressAPI -->|handles| WSRoute

    ExpressAPI -->|invokes| LogMod
    ExpressAPI -->|invokes| FxaMod
    ExpressAPI -->|invokes| StateMod
    ExpressAPI -->|invokes| ConfigMod

    ExpressAPI -->|storage operations| StorageInterface
    StorageInterface --> FSAdapter
    StorageInterface --> S3Adapter
    StorageInterface --> GCSAdapter
    StorageInterface --> RedisAdapter

    ExpressAPI -->|queries| RedisCluster
    ExpressAPI -->|OAuth calls| FxaAuth

    ExpressAPI -->|WSS| WSRoute

    PublicAssets -->|served via| CDN
    WebSPA --> SW
    WebSPA --> Routing
    WebSPA --> Streams
    WebSPA --> UI

    %% Click Events
    click WebSPA "https://github.com/timvisee/send/tree/master/app/"
    click PublicAssets "https://github.com/timvisee/send/tree/master/public/"
    click SW "https://github.com/timvisee/send/blob/master/app/serviceWorker.js"
    click Routing "https://github.com/timvisee/send/blob/master/app/routes.js"
    click Streams "https://github.com/timvisee/send/blob/master/app/streams.js"
    click Streams "https://github.com/timvisee/send/blob/master/app/zip.js"
    click UI "https://github.com/timvisee/send/tree/master/app/ui/"
    click ExpressAPI "https://github.com/timvisee/send/tree/master/server/"
    click AuthMW "https://github.com/timvisee/send/blob/master/server/middleware/auth.js"
    click LangMW "https://github.com/timvisee/send/blob/master/server/middleware/language.js"
    click RateLimit "https://github.com/timvisee/send/blob/master/server/limiter.js"
    click UploadRoute "https://github.com/timvisee/send/blob/master/server/routes/upload.js"
    click DownloadRoute "https://github.com/timvisee/send/blob/master/server/routes/download.js"
    click MetadataRoute "https://github.com/timvisee/send/blob/master/server/routes/metadata.js"
    click WSRoute "https://github.com/timvisee/send/blob/master/server/routes/ws.js"
    click LogMod "https://github.com/timvisee/send/blob/master/server/log.js"
    click FxaMod "https://github.com/timvisee/send/blob/master/server/fxa.js"
    click StateMod "https://github.com/timvisee/send/blob/master/server/state.js"
    click ConfigMod "https://github.com/timvisee/send/blob/master/server/config.js"
    click StorageInterface "https://github.com/timvisee/send/blob/master/server/storage/index.js"
    click FSAdapter "https://github.com/timvisee/send/blob/master/server/storage/fs.js"
    click S3Adapter "https://github.com/timvisee/send/blob/master/server/storage/s3.js"
    click GCSAdapter "https://github.com/timvisee/send/blob/master/server/storage/gcs.js"
    click RedisAdapter "https://github.com/timvisee/send/blob/master/server/storage/redis.js"
    click AndroidApp "https://github.com/timvisee/send/tree/master/android/"
    click iOSApp "https://github.com/timvisee/send/tree/master/ios/send-ios/"
    click CLI "https://github.com/timvisee/send/tree/master/scripts/ffsend"
    click CDN "https://github.com/timvisee/send/tree/master/scripts/"
    classDef client fill:#cce5ff,stroke:#004085,color:#004085
    classDef app fill:#d4edda,stroke:#155724,color:#155724
    classDef storage fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
