Game sync and live services for independent game developers (targeting itch.io)
1# Requirements
2
3## Functional Requirements
4
5### 1. Storage Management
6- 2GB default quota per user (soft limits at 80%, cumulative tracking)
7- Hard limit enforcement when quota exceeded
8- Cumulative tracking (never resets)
9- Blob count limits (default: 1000)
10
11### 2. GDPR Compliance
12- Automatic EU country detection via GeoLite2 database
13- EU users must store data in EU data centers
14- Non-EU users can use default backend
15- Country detection failure must crash application
16- GeoLite2 database path configurable via `GEOIP_DATABASE_PATH` environment variable
17- Block uploads until country is set in profile
18- Provide country consent flow with GDPR alerts
19
20### 3. Multi-Backend Storage
21- Bunny Storage support (default backend)
22- DigitalOcean Spaces support (alternative backend)
23- Real-time cost calculation from backend APIs
24- 1-hour cost cache with automatic background refresh
25- Backend selection based on user location (GDPR-compliant)
26- Automatic storage backups (Bunny built-in: 7-day retention)
27
28### 4. Authentication
29- JWT for XRPC endpoints (24-hour expiration)
30- Passkey for admin CLI (terminal-only, no web UI)
31- Terminal registration via single interactive command with QR code
32- HTTP endpoint for credential response (from phone)
33- Age encryption for passkeys database (synced to Bunny Storage)
34- Session cookies for web UI (7-day expiration)
35- Session cookies created after country consent
36- HTTP-only, Secure, SameSite=Lax settings for cookies
37
38### 5. Passkey Management
39- Terminal-only registration (no web UI)
40- Single interactive command: `scrtchbk-ctl passkey-register <username>`
41- Display QR code in terminal (ASCII art)
42- Wait for HTTP POST `/auth/passkey/response` from phone
43- Store credentials in passkeys database
44- Encrypt passkeys database with age
45- Sync to Bunny Storage bucket after every registration
46- Encryption key loaded from `.env.age` environment variable
47- 5-minute timeout for credential response
48
49### 6. Cost Management
50- Real-time storage cost per GB (Bunny: $0.01, DO: $0.005)
51- Real-time bandwidth cost per GB (Bunny: $0.005, DO: $0.008)
52- Combined total cost calculation
53- 1-hour cache duration
54- Automatic background refresh task (tokio)
55- Cached using `cached` proc macro for memoization
56- Cache cleared every hour to force recalculation
57- Individual backend costs cached separately
58- Combined total cost cached separately
59
60### 7. Admin Controls
61- CLI tool named `scrtchbk-ctl`
62- Direct database access (no authentication required)
63- System statistics command
64- User management commands (list, view, set quota)
65- Blob management commands (list, soft delete)
66- Cleanup command for expired soft-deleted blobs (14-day retention)
67- Passkey commands (register, sync)
68- Database query commands
69- Static binary (separate build.sr.ht)
70
71### 8. Web UI
72- Homepage with deployment information and real-time cost estimates
73- Protected self-view page (session cookie auth required)
74- Country consent flow page
75- HTMX for dynamic interactions
76- minijinja templates with Object contexts
77- 7-day session cookie expiration
78- HTTP-only, Secure, SameSite=Lax cookie settings
79
80### 9. Configuration
81- Priority: Environment variables > config.toml > defaults
82- Age decryption on startup (`.env.age`)
83- GeoLite2 database path via `GEOIP_DATABASE_PATH` environment variable
84- Session cookie configuration (7-day expiration)
85- Separate build.sr.ht for admin CLI
86
87### 10. Deployment
88- Deployment metadata generated fresh at every startup
89- Static binary builds via build.sr.ht
90- No CI/CD (manual deployment to Hetzner VPS)
91- Deployment info stored in `deployment-info.json`
92
93## Non-Functional Requirements
94
95### 1. Technology Stack
96- Rust 2021 edition
97- Axum 0.7 (web framework)
98- Diesel 2.1 (ORM)
99- SQLite (database via rsky)
100- minijinja 2.0 (templates)
101- age 0.11 (encryption)
102- cached 0.1 (memoization)
103- fs-err-tokio 0.2 (error handling)
104- webauthn-rs 0.5 (passkey)
105- aws-sdk-s3 1.20 (Bunny/DigitalOcean)
106- maxminddb 0.24 (GeoIP)
107- qrcode 0.14 (QR codes)
108- cookie 0.18 (session cookies)
109
110### 2. Performance
111- Cost calculations cached for 1 hour
112- Background refresh task for cache
113- Async/await throughout
114- Connection pooling for databases
115- Real-time API calls to storage backends
116
117### 3. Security
118- Zero-knowledge (server cannot decrypt user data)
119- Age encryption at rest (passkeys in Bunny Storage)
120- HTTPS-only for production
121- Secure cookies (HTTP-only, Secure flag, SameSite=Lax)
122- JWT tokens (24-hour expiration)
123- Session tokens (7-day expiration)
124- Separate passkeys database for admin credentials
125
126### 4. Reliability
127- Bunny Storage 99.95% uptime SLA
128- DigitalOcean Spaces 99.9% uptime SLA
129- Soft deletion with 14-day retention (grace period for recovery)
130- Automatic storage backups (Bunny built-in, 7-day retention)
131- GeoIP detection with crash on failure (admin must configure)
132
133### 5. Usability
134- Terminal-only passkey registration with QR codes
135- Clear error messages for configuration failures
136- GDPR consent flow with storage restrictions explained
137- Mobile-responsive HTMX interface
138- Real-time cost estimates on homepage
139
140### 6. Maintainability
141- Separate admin CLI from web server
142- Comprehensive documentation
143- Diesel migrations for schema changes
144- Build.sr.ht for reproducible deployments
145- Error handling with miette for detailed diagnostics
146
147### 7. Scalability
148- Dual storage backends (Bunny + DigitalOcean)
149- GDPR-compliant region routing
150- Cost cache reduces API calls
151- Connection pooling for databases
152- Background tasks for non-blocking operations
153
154## Constraints
155
156- Budget: $80/month maximum
157 - Hetzner EU VPS: $5.50
158 - DigitalOcean US VPS: $12 (upgraded)
159 - Bunny Storage: $11 total (separate EU/US buckets)
160 - Sentry: $15 (team plan)
161 - uptime.io: $7
162 - Elastic Email: $5
163 - Turso: $10 (for metadata only)
164
165- Storage backends must be S3-compatible
166- Passkey registration must be terminal-only
167- GeoIP database must be configured before starting
168- Application must crash if GeoIP detection fails
169- Session cookies must expire after 7 days
170- Soft-deleted blobs must be retained for 14 days
171- Cost cache must refresh every hour
172- Passkeys must sync to Bunny Storage after registration
173- Age encryption key must be in `.env.age`