Architecture Overview

System diagram

┌─────────────┐     HTTPS      ┌───────────────┐     HTTP      ┌──────────────────┐
│   Browser    │ ──────────────→│ Reverse Proxy │ ────────────→│    RustyFile      │
│  (React SPA) │ ←──────────────│ (nginx/Caddy) │ ←────────────│   (Axum/Tokio)   │
└─────────────┘                └───────────────┘              └──────┬───────────┘
                                                                     │
                                           ┌─────────────────────────┼─────────────┐
                                           │                         │             │
                                      ┌────▼────┐            ┌──────▼──┐    ┌─────▼─────┐
                                      │ SQLite  │            │  Files  │    │  FFmpeg   │
                                      │ (WAL)   │            │  (disk) │    │ (optional)│
                                      └─────────┘            └─────────┘    └───────────┘

Tech stack

Layer	Technology
HTTP framework	Axum 0.8
Async runtime	Tokio (multi-threaded)
Database	SQLite (bundled via rusqlite, WAL mode)
Connection pool	deadpool-sqlite (4 connections)
Auth	JWT HS256 + Argon2id
Config	Figment (TOML + env + defaults) + Clap (CLI)
Logging	tracing + tracing-subscriber (pretty or JSON)
Frontend	React 19 + TypeScript + Tailwind CSS 4
Build	Cargo (Rust) + Vite (frontend)
Frontend embedding	rust-embed (optional, default on)

Project structure

• Directorysrc/

  • main.rs — Entry point, startup wiring
  • lib.rs — Module declarations
  • config.rs — Layered configuration
  • state.rs — Shared AppState
  • error.rs — Unified error type
  • frontend.rs — Embedded SPA serving
  • Directoryapi/

    • mod.rs — Router + middleware stack
    • auth.rs — Login, logout, refresh
    • setup.rs — First-run admin creation
    • files.rs — Browse, create, delete, rename
    • download.rs — Range-request file streaming
    • tus.rs — TUS 1.0 upload protocol
    • thumbs.rs — Image thumbnails
    • hls.rs — HLS playlist + segments
    • search.rs — Full-text search endpoint
    • health.rs — Health check
    • Directorymiddleware/

      • auth.rs — JWT validation middleware
      • rate_limit.rs — Per-IP API rate limiting
  • Directorydb/

    • mod.rs — Pool, migrations, interact helper
    • user_repo.rs — User CRUD + password hashing
  • Directoryservices/

    • file_ops.rs — Path safety, listing, atomic writes
    • cache.rs — Directory listing cache (moka)
    • thumbnail.rs — Image resize + disk cache
    • transcoder.rs — FFmpeg HLS transcoder
    • search_index.rs — SQLite FTS5 search indexer
• Directoryfrontend/

  • Directorysrc/

    • App.tsx — Router, auth guard
    • api/client.ts — Fetch wrapper, token management
    • Directoryhooks/ — useAuth, useFiles, useTusUpload, useDragDrop, useSearch

      • …
    • Directorypages/ — LoginPage, BrowserPage, EditorPage, PlayerPage, PreviewPage

      • …
    • Directorycomponents/ — Layout, FileList, UploadManager, VideoControls

      • …
    • Directorylib/ — Types, path utils, formatting

      • …
• Directorymigrations/

  • V1__initial_schema.sql
  • V2__tus_and_cache.sql
  • V3__search_index.sql
• Cargo.toml
• Dockerfile
• Makefile

Request lifecycle

1. Request arrives at Axum router
2. Tower middleware stack applies: CORS, compression (gzip/brotli), security headers, tracing, timeout, body limit
3. For protected routes, require_auth middleware extracts JWT (Bearer header or cookie), validates signature and expiry, looks up user in SQLite, injects User as an Axum extension
4. Handler executes business logic (file ops, uploads, etc.)
5. Response flows back through middleware (compression, tracing span close)

Shared state

All handlers share an AppState struct containing:

• SQLite connection pool
• Canonical root path
• Configuration values (Arc-wrapped)
• JWT secret
• Directory listing cache (moka)
• HLS source mapping (moka cache)
• Thumbnail worker and HLS transcoder
• Login rate limiter (10 attempts / 15 min per IP)
• API rate limiter (configurable, default 60/min per IP)
• Token blocklist (moka cache)
• Blocked upload extensions (pre-parsed HashSet)
• Search indexer (SearchIndexer)
• Setup guard (AtomicBool + deadline)
• Dummy hash for constant-time login failure