# abel-ajish/filesend architecture

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

- Interactive diagram: https://gitdiagram.com/abel-ajish/filesend
- Repository: https://github.com/abel-ajish/filesend

## Overview

**Local Share** is a **single Next.js 14 App Router web app** deployed on **Vercel** that provides **temporary file sharing** with two transfer paths:

1. **P2P path (preferred):** Browser ↔ Browser over **WebRTC** (same network / QR mode), using STUN/TURN infrastructure as needed.
2. **Server fallback path:** Browser ↔ **Next.js API routes** ↔ **Appwrite Cloud Storage** (public files), with **auto-delete ~60s**.

- **UI + WebRTC logic in the browser**
- **thin server-side API routes** (Next.js serverless functions)
- **Appwrite as the persistent component (short-lived storage)**
- optional external **STUN/TURN** dependencies for WebRTC

##### Frontend (Browser)
- `app/page.tsx` – main workflow page (upload/send/receive UI)
- `app/layout.tsx`, `app/globals.css` – shell + styling
- `components/file-share.tsx` – core UI component(s) for sharing flow
- `lib/p2p.ts` – WebRTC / peer connection / data channel logic (P2P mode)
- QR code mode is a **UI feature** (likely in components/page logic) that influences how peers connect (share SDP/offer info or a room/code).

##### Backend (Next.js API routes running on Vercel)
- `app/api/files/route.ts` – `POST /api/files` (upload entrypoint)
- `app/api/files/[filename]/route.ts` – `DELETE /api/files/:filename` (explicit delete / lifecycle cleanup)
- `app/api/code/[code]/route.ts` – `GET /api/code/:code` (resolve a 6-char code to file metadata / download info)

These are **serverless** in Vercel terms (stateless, invoked per request).

##### External Storage / Backend Service
- `lib/appwrite.ts` – Appwrite SDK wrapper / client configuration for API routes
- Appwrite Cloud: bucket `files` (per README), using API key with `files.read`, `files.write`.

##### Configuration/Deployment
- `.env.example` – required runtime config (Appwrite endpoint, project, key, bucket)
- `next.config.mjs`, `tsconfig.json`, etc.
- Vercel is the runtime target (README + badge).

##### Sender Browser (Next.js client)
- Upload UI
- WebRTC sender
- QR generator (or code display)
##### Receiver Browser (Next.js client)
- Download UI
- WebRTC receiver
- QR scanner (if supported)
##### Next.js on Vercel
- Static/SSR hosting for the UI
- **API Route: POST /api/files**
- **API Route: GET /api/code/:code**
- **API Route: DELETE /api/files/:filename**
##### Appwrite Cloud
- Storage bucket `files`
- File object (filename/id, public URL, metadata/code)
##### WebRTC Infrastructure (External)
- STUN (and TURN if used/needed)
- This is critical to show because it explains “P2P works sometimes, falls back otherwise”.

##### Deletion
- Either scheduled client-side timer triggers `DELETE /api/files/:filename`
- Or server-side logic triggers deletion after ~60s (if implemented in API route)

##### Important architectural patterns present in this repo

- **App Router + Route Handlers**: backend logic lives under `app/api/**/route.ts` (serverless endpoints).
- **Thin backend / externalized storage**: no custom DB; Appwrite is the persistence layer.
- **Dual-path transport**: WebRTC P2P first, **fallback** to Appwrite-hosted download.
- **Stateless compute**: Vercel serverless functions; do not assume in-memory state for code mapping (if code lookup exists, it must be derivable from storage metadata or deterministic naming).

##### What to label explicitly (to make it “accurate”, not generic)
Labels because they’re core requirements from README:

- “**No login / no accounts**” (security/trust note)
- “**Auto-delete ~60 seconds**” near lifecycle mechanism
- “**6-character code**” between “upload result” and “receiver lookup”

##### Quick checklist of “components to separate as much as possible”
To follow “don’t overthink it; separate into many components”, include these as distinct nodes:
- Upload UI
- Code generation/display
- QR encode/decode
- WebRTC sender
- WebRTC receiver
- P2P signaling exchange (QR/manual)
- Fallback upload API route
- Code resolution API route
- Delete API route
- Appwrite bucket
- Appwrite public download endpoint
- STUN and TURN (even if TURN is “optional/unknown”)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% C4 L1 — Context
%% =========================
subgraph "C4 L1 — Context (System & External Dependencies)"
  direction TB

  SenderUser["Sender (User)"]:::person
  ReceiverUser["Receiver (User)"]:::person

  subgraph "Local Share (Next.js 14 App Router Web App)"
    direction TB
    LocalShare["Local Share"]:::system
    Notes["Notes:\n- No login / no accounts\n- Dual-path transport: P2P first, fallback to server\n- Stateless compute (no in-memory state)"]:::note
  end

  VercelCloud["Vercel (Hosting + Serverless Runtime)"]:::cloud
  AppwriteCloud["Appwrite Cloud (Managed Storage)"]:::cloud
  StunTurn["WebRTC Infra: STUN (required) / TURN (optional)"]:::cloud
end

SenderUser -->|"uses"| LocalShare
ReceiverUser -->|"uses"| LocalShare

LocalShare -->|"deployed_on"| VercelCloud
LocalShare -->|"stores_short-lived_public_files"| AppwriteCloud
LocalShare -->|"uses_for_ICE_connectivity"| StunTurn

%% =========================
%% C4 L2 — Container (most important)
%% =========================
subgraph "C4 L2 — Containers (Two Transfer Paths)"
  direction TB

  subgraph "Untrusted Zone — Browsers"
    direction TB

    subgraph "Sender Browser (Next.js Client)"
      direction TB
      S_UI["Upload/Send UI"]:::client
      S_QR["QR / Code Display (6-char code)"]:::client
      S_Signal["P2P Signaling Exchange (QR/manual payload)"]:::client
      S_WebRTC["WebRTC Sender (DataChannel)"]:::client
      S_Timer["Deletion Timer (~60s)"]:::client
    end

    subgraph "Receiver Browser (Next.js Client)"
      direction TB
      R_UI["Receive/Download UI"]:::client
      R_QR["QR Scan / Code Entry (6-char code)"]:::client
      R_Signal["P2P Signaling Exchange (QR/manual payload)"]:::client
      R_WebRTC["WebRTC Receiver (DataChannel)"]:::client
    end
  end

  subgraph "Managed Services Zone"
    direction TB

    subgraph "Next.js on Vercel (App Router + Route Handlers)"
      direction TB
      HostUI["UI Hosting (Static/SSR)"]:::server
      API_Upload["API Route: POST /api/files"]:::api
      API_Code["API Route: GET /api/code/:code"]:::api
      API_Delete["API Route: DELETE /api/files/:filename"]:::api
      Stateless["Stateless serverless functions\n(no in-memory state)"]:::note
    end

    subgraph "Appwrite Cloud Storage"
      direction TB
      Bucket[("Storage Bucket: files")]:::storage
      PublicDL["Public Download Endpoint (publicUrl)\nTrusted use only"]:::external
      Lifecycle["Auto-delete ~60 seconds\n(short-lived, public files)"]:::note
    end

    subgraph "WebRTC Connectivity Services"
      direction TB
      STUN["STUN"]:::external
      TURN["TURN (optional)"]:::external
    end
  end
end

%% --- P2P Flow (preferred)
S_Signal -->|"P2P_signaling_payload (QR/manual)"| R_Signal
S_WebRTC -->|"ICE_checks"| STUN
R_WebRTC -->|"ICE_checks"| STUN
S_WebRTC -.->|"ICE_relay_if_needed"| TURN
R_WebRTC -.->|"ICE_relay_if_needed"| TURN
S_WebRTC <==>|"WebRTC DataChannel\nP2P local transfers"| R_WebRTC

%% --- Fallback Flow (server)
S_UI -->|"HTTPS POST /api/files"| API_Upload
API_Upload -->|"Appwrite SDK upload"| Bucket
API_Upload -->|"returns {code, publicUrl/fileId/filename}"| S_QR

R_QR -->|"HTTPS GET /api/code/:code"| API_Code
API_Code -->|"resolve metadata (deterministic/derivable)"| Bucket
API_Code -->|"returns download info (publicUrl/filename)"| R_UI

R_UI -->|"HTTPS GET publicUrl (Public files)"| PublicDL
PublicDL -->|"serves file"| R_UI

S_Timer -->|"HTTPS DELETE /api/files/:filename"| API_Delete
API_Delete -->|"Appwrite SDK delete"| Bucket

%% Hosting relation
HostUI -->|"serves Next.js client"| S_UI
HostUI -->|"serves Next.js client"| R_UI

%% =========================
%% C4 L3 — Component Diagram (repo-anchored)
%% =========================
subgraph "C4 L3 — Next.js App Components (Repo Anchors)"
  direction TB

  subgraph "App Router UI (app/)"
    direction TB
    Page["Main Workflow Page (Upload/Send/Receive)"]:::client
    Layout["App Shell / Layout"]:::client
    CSS["Global Styles"]:::client
  end

  subgraph "UI Components (components/)"
    direction TB
    FileShare["Core File Sharing UI / Sharing Flow"]:::client
  end

  subgraph "Client Libraries (lib/)"
    direction TB
    P2P["WebRTC P2P Logic (PeerConnection + DataChannel)"]:::client
    AWClient["Appwrite SDK Wrapper / Client Config (for API routes)"]:::server
  end

  subgraph "Route Handlers (app/api/**)"
    direction TB
    UploadRoute["POST /api/files (route handler)"]:::api
    CodeRoute["GET /api/code/:code (route handler)"]:::api
    DeleteRoute["DELETE /api/files/:filename (route handler)"]:::api
  end

  subgraph "Config / Tooling"
    direction TB
    Env["Runtime Config (.env)"]:::config
    NextCfg["Next.js Config"]:::config
    TsCfg["TypeScript Config"]:::config
  end
end

%% L3 wiring
Layout -->|"wraps"| Page
CSS -->|"styles"| Page
Page -->|"renders"| FileShare

FileShare -->|"uses"| P2P
FileShare -->|"calls (fallback)"| UploadRoute
FileShare -->|"calls (lookup)"| CodeRoute
FileShare -->|"calls (cleanup)"| DeleteRoute

UploadRoute -->|"uses"| AWClient
CodeRoute -->|"uses"| AWClient
DeleteRoute -->|"uses"| AWClient

AWClient -->|"SDK calls"| Bucket

Env -->|"provides endpoint/project/key/bucket"| AWClient
NextCfg -->|"build/runtime config"| Page
TsCfg -->|"typecheck"| Page

%% =========================
%% Click events (from component_mapping)
%% =========================
click Page "https://github.com/abel-ajish/filesend/blob/main/app/page.tsx"
click Layout "https://github.com/abel-ajish/filesend/blob/main/app/layout.tsx"
click CSS "https://github.com/abel-ajish/filesend/blob/main/app/globals.css"
click FileShare "https://github.com/abel-ajish/filesend/blob/main/components/file-share.tsx"
click P2P "https://github.com/abel-ajish/filesend/blob/main/lib/p2p.ts"
click AWClient "https://github.com/abel-ajish/filesend/blob/main/lib/appwrite.ts"
click UploadRoute "https://github.com/abel-ajish/filesend/blob/main/app/api/files/route.ts"
click DeleteRoute "https://github.com/abel-ajish/filesend/blob/main/app/api/files/[filename]/route.ts"
click CodeRoute "https://github.com/abel-ajish/filesend/blob/main/app/api/code/[code]/route.ts"
click Env "https://github.com/abel-ajish/filesend/blob/main/.env.example"
click NextCfg "https://github.com/abel-ajish/filesend/blob/main/next.config.mjs"
click TsCfg "https://github.com/abel-ajish/filesend/blob/main/tsconfig.json"

%% =========================
%% Styles (color-coded)
%% =========================
classDef person fill:#FDE68A,stroke:#92400E,stroke-width:1px,color:#111827
classDef system fill:#BFDBFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1220
classDef client fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#0B1220
classDef server fill:#E9D5FF,stroke:#7C3AED,stroke-width:1px,color:#0B1220
classDef api fill:#F5D0FE,stroke:#A21CAF,stroke-width:1px,color:#0B1220
classDef storage fill:#C7F9CC,stroke:#16A34A,stroke-width:1px,color:#052e10
classDef cloud fill:#E5E7EB,stroke:#374151,stroke-width:1px,color:#111827
classDef external fill:#D1FAE5,stroke:#059669,stroke-width:1px,color:#064E3B
classDef note fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#111827
classDef config fill:#FFE4E6,stroke:#E11D48,stroke-width:1px,color:#111827
```
