Game sync and live services for independent game developers (targeting itch.io)
1# ScratchBack PDS - Introduction
2
3## Overview
4
5ScratchBack PDS is a zero-knowledge Personal Data Store (PDS) implementing
6ATProtocol standards using rsky. This service provides cloud storage for
7itch.io game saves with GDPR compliance, conditional mobile sync, Age
8encryption, and support for both Bunny Storage and DigitalOcean Spaces.
9
10## Problem Statement
11
12itch.io game developers need a secure, GDPR-compliant cloud storage solution for player saves with:
13
14- Zero-knowledge architecture (server cannot decrypt user data)
15- GDPR compliance with EU data localization
16- Cost-effective storage with multiple backend options
17- Mobile-first with conditional sync
18- Admin controls for system management
19
20## Solution
21
22A PDS built on:
23
24- **ATProtocol**: Standards-based protocol for decentralized data storage
25- **rsky**: Rust implementation of ATProtocol PDS with SQLite backend
26- **Axum**: Modern web framework for HTTP/XRPC endpoints
27- **Age Encryption**: Zero-knowledge client-side encryption
28- **Dual Storage Backends**: Bunny Storage + DigitalOcean Spaces
29- **HTMX**: Server-side rendered web UI for admin controls
30
31## Key Features
32
33- 2GB default quota per user (soft limits at 80%, cumulative tracking)
34- GDPR-compliant automatic region routing (EU users → EU storage)
35- Real-time cost calculation (cached for 1 hour)
36- Passkey authentication (terminal-only setup with QR codes)
37- Session-based web UI (7-day expiration)
38- Country consent flow with GDPR alerts
39- Admin CLI (`scrtchbk-ctl`) for system management
40- Soft deletion with 14-day retention
41- Deployment metadata generated fresh at every startup
42- Age encryption for passkeys database (synced to Bunny Storage)
43
44## Technology Stack
45
46- Rust 2021 edition
47- Axum 0.7 (web framework)
48- Diesel 2.1 (ORM)
49- SQLite (database via rsky)
50- minijinja 2.0 (templates)
51- age 0.11 (encryption)
52- cached 0.1 (memoization)
53- webauthn-rs 0.5 (passkey)
54- aws-sdk-s3 1.20 (Bunny/DigitalOcean)
55- maxminddb 0.24 (GeoIP)
56
57## Architecture Decisions
58
591. **Separate databases**:
60 - Main database: user_quotas, blobs, sessions, ntfy_subscriptions
61 - Passkeys database: passkeys table (age-encrypted, synced to Bunny Storage)
62
632. **GDPR routing**:
64 - EU users: Stored in EU data centers (Bunny frankfurt / DO fra1)
65 - Non-EU users: Stored in US data centers (Bunny us / DO nyc3)
66 - Country detection: GeoLite2 database (configurable path via env var)
67
683. **Authentication methods**:
69 - XRPC: JWT tokens (24-hour expiration)
70 - Admin CLI: Passkey (terminal-only, QR code registration)
71 - Web UI: Session cookies (7-day expiration, HTTP-only, Secure, SameSite=Lax)
72
734. **Cost management**:
74 - Real-time API calls to Bunny/DigitalOcean
75 - 1-hour cache using `cached` proc macro
76 - Background refresh task (tokio)
77 - Individual + combined cost calculations cached
78
795. **Deployment**:
80 - Static binaries via build.sr.ht
81 - Deployment metadata generated fresh at startup (not from CI/CD)
82 - VPS deployment to Hetzner
83
84## Project Structure
85
86```
87/home/vrgl/Code/scratch-itch/
88├── mise.toml # Pinned direnv + age
89├── Cargo.toml # Workspace root
90├── .env.age # Encrypted secrets
91├── config.toml # Default configuration
92├── deployment-info.json # Deployment metadata (generated)
93├── build.sr.ht # Build configuration
94├── Cargo.lock
95├── src/
96│ ├── main.rs
97│ ├── config/
98│ ├── storage/
99│ ├── quota/
100│ ├── auth/
101│ ├── xrpc/
102│ ├── web/
103│ ├── deployment/
104│ ├── cost_cache/
105│ ├── models/
106│ └── error.rs
107├── migrations/ # Diesel migrations (main DB)
108├── passkeys-migrations/ # Diesel migrations (passkeys DB)
109├── static/
110│ ├── css/
111│ └── js/
112└── cli/ # scrtchbk-ctl binary
113 ├── Cargo.toml
114 └── build.sr.ht
115```
116
117## Documentation
118
119- [Architecture](docs/initial-plan/01-architecture.md)
120- [Requirements](docs/initial-plan/02-requirements.md)
121- [Data Model](docs/initial-plan/03-data-model.md)
122- [Implementation Phases](docs/initial-plan/04-implementation-phases.md)
123- [ADR - Platform Introduction](docs/initial-plan/ADR.md)
124
125## Implementation Timeline
126
127- Phase 1: Foundation
128- Phase 2: Configuration System
129- Phase 3: Storage Layer
130- Phase 4: Passkey Storage
131- Phase 5: Quota System
132- Phase 6: Cost Cache
133- Phase 7: Authentication
134- Phase 8: Deployment Tracking
135- Phase 9: XRPC Endpoints
136- Phase 10: Web UI
137- Phase 11: Admin CLI
138- Phase 12: Testing & Deployment