Requirements#

Functional Requirements#

1. Storage Management#

• 2GB default quota per user (soft limits at 80%, cumulative tracking)
• Hard limit enforcement when quota exceeded
• Cumulative tracking (never resets)
• Blob count limits (default: 1000)

2. GDPR Compliance#

• Automatic EU country detection via GeoLite2 database
• EU users must store data in EU data centers
• Non-EU users can use default backend
• Country detection failure must crash application
• GeoLite2 database path configurable via GEOIP_DATABASE_PATH environment variable
• Block uploads until country is set in profile
• Provide country consent flow with GDPR alerts

3. Multi-Backend Storage#

• Bunny Storage support (default backend)
• DigitalOcean Spaces support (alternative backend)
• Real-time cost calculation from backend APIs
• 1-hour cost cache with automatic background refresh
• Backend selection based on user location (GDPR-compliant)
• Automatic storage backups (Bunny built-in: 7-day retention)

4. Authentication#

• JWT for XRPC endpoints (24-hour expiration)
• Passkey for admin CLI (terminal-only, no web UI)
• Terminal registration via single interactive command with QR code
• HTTP endpoint for credential response (from phone)
• Age encryption for passkeys database (synced to Bunny Storage)
• Session cookies for web UI (7-day expiration)
• Session cookies created after country consent
• HTTP-only, Secure, SameSite=Lax settings for cookies

5. Passkey Management#

• Terminal-only registration (no web UI)
• Single interactive command: scrtchbk-ctl passkey-register <username>
• Display QR code in terminal (ASCII art)
• Wait for HTTP POST /auth/passkey/response from phone
• Store credentials in passkeys database
• Encrypt passkeys database with age
• Sync to Bunny Storage bucket after every registration
• Encryption key loaded from .env.age environment variable
• 5-minute timeout for credential response

6. Cost Management#

• Real-time storage cost per GB (Bunny: $0.01, DO: $0.005)
• Real-time bandwidth cost per GB (Bunny: $0.005, DO: $0.008)
• Combined total cost calculation
• 1-hour cache duration
• Automatic background refresh task (tokio)
• Cached using cached proc macro for memoization
• Cache cleared every hour to force recalculation
• Individual backend costs cached separately
• Combined total cost cached separately

7. Admin Controls#

• CLI tool named scrtchbk-ctl
• Direct database access (no authentication required)
• System statistics command
• User management commands (list, view, set quota)
• Blob management commands (list, soft delete)
• Cleanup command for expired soft-deleted blobs (14-day retention)
• Passkey commands (register, sync)
• Database query commands
• Static binary (separate build.sr.ht)

8. Web UI#

• Homepage with deployment information and real-time cost estimates
• Protected self-view page (session cookie auth required)
• Country consent flow page
• HTMX for dynamic interactions
• minijinja templates with Object contexts
• 7-day session cookie expiration
• HTTP-only, Secure, SameSite=Lax cookie settings

9. Configuration#

• Priority: Environment variables > config.toml > defaults
• Age decryption on startup (.env.age)
• GeoLite2 database path via GEOIP_DATABASE_PATH environment variable
• Session cookie configuration (7-day expiration)
• Separate build.sr.ht for admin CLI

10. Deployment#

• Deployment metadata generated fresh at every startup
• Static binary builds via build.sr.ht
• No CI/CD (manual deployment to Hetzner VPS)
• Deployment info stored in deployment-info.json

Non-Functional Requirements#

1. Technology Stack#

• Rust 2021 edition
• Axum 0.7 (web framework)
• Diesel 2.1 (ORM)
• SQLite (database via rsky)
• minijinja 2.0 (templates)
• age 0.11 (encryption)
• cached 0.1 (memoization)
• fs-err-tokio 0.2 (error handling)
• webauthn-rs 0.5 (passkey)
• aws-sdk-s3 1.20 (Bunny/DigitalOcean)
• maxminddb 0.24 (GeoIP)
• qrcode 0.14 (QR codes)
• cookie 0.18 (session cookies)

2. Performance#

• Cost calculations cached for 1 hour
• Background refresh task for cache
• Async/await throughout
• Connection pooling for databases
• Real-time API calls to storage backends

3. Security#

• Zero-knowledge (server cannot decrypt user data)
• Age encryption at rest (passkeys in Bunny Storage)
• HTTPS-only for production
• Secure cookies (HTTP-only, Secure flag, SameSite=Lax)
• JWT tokens (24-hour expiration)
• Session tokens (7-day expiration)
• Separate passkeys database for admin credentials

4. Reliability#

• Bunny Storage 99.95% uptime SLA
• DigitalOcean Spaces 99.9% uptime SLA
• Soft deletion with 14-day retention (grace period for recovery)
• Automatic storage backups (Bunny built-in, 7-day retention)
• GeoIP detection with crash on failure (admin must configure)

5. Usability#

• Terminal-only passkey registration with QR codes
• Clear error messages for configuration failures
• GDPR consent flow with storage restrictions explained
• Mobile-responsive HTMX interface
• Real-time cost estimates on homepage

6. Maintainability#

• Separate admin CLI from web server
• Comprehensive documentation
• Diesel migrations for schema changes
• Build.sr.ht for reproducible deployments
• Error handling with miette for detailed diagnostics

7. Scalability#

• Dual storage backends (Bunny + DigitalOcean)
• GDPR-compliant region routing
• Cost cache reduces API calls
• Connection pooling for databases
• Background tasks for non-blocking operations

Constraints#

• Budget: $80/month maximum

  • Hetzner EU VPS: $5.50
  • DigitalOcean US VPS: $12 (upgraded)
  • Bunny Storage: $11 total (separate EU/US buckets)
  • Sentry: $15 (team plan)
  • uptime.io: $7
  • Elastic Email: $5
  • Turso: $10 (for metadata only)

• Storage backends must be S3-compatible

• Passkey registration must be terminal-only

• GeoIP database must be configured before starting

• Application must crash if GeoIP detection fails

• Session cookies must expire after 7 days

• Soft-deleted blobs must be retained for 14 days

• Cost cache must refresh every hour

• Passkeys must sync to Bunny Storage after registration

• Age encryption key must be in .env.age