feat(server): add storage abstraction layer for image handling

- Create storage/types.js with StorageAdapter interface
- Create storage/filesystem-adapter.js with sync/async methods
- Create storage/index.js factory for storage adapter selection
- Refactor db.js saveImage/getImageData to use storage adapter
- Refactor index.js image serving to use getImageData
- Hash-based storage keys for content-addressable storage

Prepares for future R2/S3 backend switching.

resolve: regenerate schema files

backend/server/db.js

···
 const { sqlFactory } = require("./sql");
+const { createStorageAdapter } = require("./storage");
 const path = require("path");
 const crypto = require("crypto");
 const fs = require("fs");
···
 // Connection pool - one connection per user:profile
 // Now stores SqlAdapter instances instead of raw Database instances
 const connections = new Map();
+
+// Storage adapter pool - one per user:profile
+const storageAdapters = new Map();
+
+/**
+ * Get storage adapter for a user's profile.
+ * @param {string} userId
+ * @param {string} [profileId='default']
+ * @returns {import('./storage/types').StorageAdapter}
+ */
+function getStorageAdapter(userId, profileId = "default") {
+  const key = `${userId}:${profileId}`;
+  if (storageAdapters.has(key)) {
+    return storageAdapters.get(key);
+  }
+
+  const profileDir = path.join(DATA_DIR, userId, "profiles", profileId);
+  const imagesDir = path.join(profileDir, "images");
+
+  const adapter = createStorageAdapter({
+    type: "filesystem",
+    basePath: imagesDir,
+  });
+
+  storageAdapters.set(key, adapter);
+  return adapter;
+}
 
 function getConnection(userId, profileId = "default") {
   if (!userId) {
···
   }
 
   const conn = getConnection(userId, profileId);
+  const storage = getStorageAdapter(userId, profileId);
   const timestamp = now();
 
-  // Compute hash for file deduplication (not item dedup)
+  // Compute hash for content-addressable storage
   const hash = hashBuffer(buffer);
   const ext = getExtensionFromMime(mimeType);
-  const imageFilename = `${hash}.${ext}`;
-
-  // Ensure images directory exists
-  const imagesDir = getUserImagesDir(userId, profileId);
-  if (!fs.existsSync(imagesDir)) {
-    fs.mkdirSync(imagesDir, { recursive: true });
-  }
 
-  const imagePath = path.join(imagesDir, imageFilename);
+  // Storage key is hash-based for easy backend switching
+  // Key format: {hash}.{ext} (e.g., "abc123...def.jpg")
+  const storageKey = `${hash}.${ext}`;
 
-  // Write file only if it doesn't exist (file-level dedup)
-  if (!fs.existsSync(imagePath)) {
-    fs.writeFileSync(imagePath, buffer);
-  }
+  // Store via adapter (uses sync method for filesystem adapter)
+  storage.putSync(storageKey, buffer, { mime: mimeType });
 
   // Create item record
   const itemId = generateUUID();
···
 
   const imagesDir = getUserImagesDir(userId, profileId);
   return path.join(imagesDir, `${image.metadata.hash}.${image.metadata.ext}`);
+}
+
+/**
+ * Get image data using storage adapter.
+ * Returns the raw image buffer for serving.
+ *
+ * @param {string} userId
+ * @param {string} itemId
+ * @param {string} [profileId='default']
+ * @returns {{buffer: Buffer, metadata: Object, filename: string} | null}
+ */
+function getImageData(userId, itemId, profileId = "default") {
+  const image = getImageById(userId, itemId, profileId);
+  if (!image || !image.metadata.hash) return null;
+
+  const storage = getStorageAdapter(userId, profileId);
+  const storageKey = `${image.metadata.hash}.${image.metadata.ext}`;
+
+  const buffer = storage.getSync(storageKey);
+  if (!buffer) return null;
+
+  return {
+    buffer,
+    metadata: image.metadata,
+    filename: image.filename,
+  };
 }
 
 function deleteImage(userId, itemId, profileId = "default") {
···
   getConnection,
   closeAllConnections,
   closeConnection,
+  getStorageAdapter,
   // Unified functions
   saveItem,
   getItems,
···
   getImages,
   getImageById,
   getImagePath,
+  getImageData,
   deleteImage,
   MAX_IMAGE_SIZE,
   // Backward-compatible (URLs)

backend/server/index.js

···
   const profileId = users.resolveProfileId(userId, c.req.query("profile") || "default");
   const id = c.req.param("id");
 
-  const image = db.getImageById(userId, id, profileId);
-  if (!image) {
+  const imageData = db.getImageData(userId, id, profileId);
+  if (!imageData) {
     return c.json({ error: "image not found" }, 404);
   }
 
-  const imagePath = db.getImagePath(userId, id, profileId);
-  if (!imagePath || !fs.existsSync(imagePath)) {
-    return c.json({ error: "image file not found" }, 404);
-  }
-
-  const fileBuffer = fs.readFileSync(imagePath);
-  return new Response(fileBuffer, {
+  return new Response(imageData.buffer, {
     headers: {
-      "Content-Type": image.metadata.mime,
-      "Content-Length": fileBuffer.length.toString(),
-      "Content-Disposition": `inline; filename="${image.filename}"`,
+      "Content-Type": imageData.metadata.mime,
+      "Content-Length": imageData.buffer.length.toString(),
+      "Content-Disposition": `inline; filename="${imageData.filename}"`,
     },
   });
 });

backend/server/storage/filesystem-adapter.js

···
+/**
+ * Filesystem Storage Adapter
+ *
+ * Implements StorageAdapter interface for local filesystem storage.
+ * Used for development and self-hosted deployments.
+ *
+ * Provides both sync and async methods - sync for filesystem (local),
+ * async interface ready for cloud storage backends.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * @typedef {import('./types').StorageAdapter} StorageAdapter
+ */
+
+/**
+ * @implements {StorageAdapter}
+ */
+class FilesystemAdapter {
+  /**
+   * @param {string} basePath - Base directory for all storage operations
+   */
+  constructor(basePath) {
+    /** @private */
+    this.basePath = basePath;
+  }
+
+  /**
+   * Store data at the specified key (sync version).
+   * Creates parent directories if they don't exist.
+   * Implements file-level deduplication by skipping writes if file exists.
+   *
+   * @param {string} key - Storage key (relative path)
+   * @param {Buffer} data - Data to store
+   * @param {Record<string, string>} [metadata] - Optional metadata (ignored for filesystem)
+   */
+  putSync(key, data, metadata) {
+    const fullPath = path.join(this.basePath, key);
+    const dir = path.dirname(fullPath);
+
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    // Skip write if file already exists (content-addressable dedup)
+    if (!fs.existsSync(fullPath)) {
+      fs.writeFileSync(fullPath, data);
+    }
+  }
+
+  /**
+   * Store data at the specified key (async version).
+   * @param {string} key - Storage key (relative path)
+   * @param {Buffer} data - Data to store
+   * @param {Record<string, string>} [metadata] - Optional metadata (ignored for filesystem)
+   */
+  async put(key, data, metadata) {
+    this.putSync(key, data, metadata);
+  }
+
+  /**
+   * Retrieve data by key (sync version).
+   *
+   * @param {string} key - Storage key
+   * @returns {Buffer|null} Data or null if not found
+   */
+  getSync(key) {
+    const fullPath = path.join(this.basePath, key);
+    return fs.existsSync(fullPath) ? fs.readFileSync(fullPath) : null;
+  }
+
+  /**
+   * Retrieve data by key (async version).
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<Buffer|null>} Data or null if not found
+   */
+  async get(key) {
+    return this.getSync(key);
+  }
+
+  /**
+   * Delete data by key (sync version).
+   *
+   * @param {string} key - Storage key
+   */
+  deleteSync(key) {
+    const fullPath = path.join(this.basePath, key);
+    if (fs.existsSync(fullPath)) {
+      fs.unlinkSync(fullPath);
+    }
+  }
+
+  /**
+   * Delete data by key (async version).
+   *
+   * @param {string} key - Storage key
+   */
+  async delete(key) {
+    this.deleteSync(key);
+  }
+
+  /**
+   * Check if key exists (sync version).
+   *
+   * @param {string} key - Storage key
+   * @returns {boolean}
+   */
+  existsSync(key) {
+    return fs.existsSync(path.join(this.basePath, key));
+  }
+
+  /**
+   * Check if key exists (async version).
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<boolean>}
+   */
+  async exists(key) {
+    return this.existsSync(key);
+  }
+
+  /**
+   * List all keys with optional prefix (sync version).
+   * Recursively walks directory structure.
+   *
+   * @param {string} [prefix] - Optional prefix to filter keys
+   * @returns {string[]} Array of keys
+   */
+  listSync(prefix) {
+    const searchPath = prefix
+      ? path.join(this.basePath, prefix)
+      : this.basePath;
+
+    if (!fs.existsSync(searchPath)) {
+      return [];
+    }
+
+    const results = [];
+    const walk = (dir) => {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(fullPath);
+        } else {
+          // Convert back to key format (relative to basePath)
+          const key = path.relative(this.basePath, fullPath);
+          results.push(key);
+        }
+      }
+    };
+
+    const stat = fs.statSync(searchPath);
+    if (stat.isDirectory()) {
+      walk(searchPath);
+    } else {
+      // prefix points to a file
+      results.push(path.relative(this.basePath, searchPath));
+    }
+
+    return results;
+  }
+
+  /**
+   * List all keys with optional prefix (async version).
+   *
+   * @param {string} [prefix] - Optional prefix to filter keys
+   * @returns {Promise<string[]>} Array of keys
+   */
+  async list(prefix) {
+    return this.listSync(prefix);
+  }
+}
+
+module.exports = { FilesystemAdapter };

backend/server/storage/index.js

···
+/**
+ * Storage Adapter Factory
+ *
+ * Selects and configures the appropriate storage adapter based on environment.
+ * Supports filesystem (default), with R2/S3 support planned for future.
+ */
+
+const { FilesystemAdapter } = require("./filesystem-adapter");
+
+/**
+ * @typedef {import('./types').StorageAdapter} StorageAdapter
+ * @typedef {import('./types').StorageConfig} StorageConfig
+ */
+
+const STORAGE_TYPE = process.env.STORAGE_TYPE || "filesystem";
+
+/**
+ * Create a storage adapter based on configuration.
+ *
+ * @param {StorageConfig} config - Storage configuration
+ * @returns {StorageAdapter}
+ */
+function createStorageAdapter(config) {
+  switch (config.type) {
+    case "filesystem":
+      if (!config.basePath) {
+        throw new Error("basePath required for filesystem storage");
+      }
+      return new FilesystemAdapter(config.basePath);
+
+    case "r2":
+      // TODO: Implement R2 adapter
+      throw new Error("R2 storage adapter not yet implemented");
+
+    case "s3":
+      // TODO: Implement S3 adapter
+      throw new Error("S3 storage adapter not yet implemented");
+
+    default:
+      throw new Error(`Unknown storage type: ${config.type}`);
+  }
+}
+
+/**
+ * Get storage type from environment.
+ *
+ * @returns {'filesystem' | 'r2' | 's3'}
+ */
+function getStorageType() {
+  return STORAGE_TYPE;
+}
+
+module.exports = { createStorageAdapter, getStorageType, FilesystemAdapter };

backend/server/storage/types.js

···
+/**
+ * Storage Abstraction Layer Types
+ *
+ * Abstracts blob/file storage to support multiple backends:
+ * - Filesystem (Node.js, current)
+ * - Cloudflare R2 (future)
+ * - S3-compatible (future)
+ *
+ * @typedef {Object} StorageAdapter
+ * @property {function(string, Buffer, Record<string, string>?): Promise<void>} put - Store data at key
+ * @property {function(string): Promise<Buffer|null>} get - Retrieve data by key
+ * @property {function(string): Promise<void>} delete - Delete data by key
+ * @property {function(string): Promise<boolean>} exists - Check if key exists
+ * @property {function(string?): Promise<string[]>} list - List keys with optional prefix
+ *
+ * @typedef {Object} StorageConfig
+ * @property {'filesystem' | 'r2' | 's3'} type - Storage backend type
+ * @property {string} [basePath] - Base path for filesystem storage
+ * @property {string} [bucket] - Bucket name for R2/S3
+ * @property {string} [region] - Region for S3
+ * @property {string} [accessKeyId] - Access key ID for S3
+ * @property {string} [secretAccessKey] - Secret access key for S3
+ * @property {string} [endpoint] - Custom endpoint for S3-compatible storage
+ */
+
+// Export empty object - types are defined via JSDoc above
+module.exports = {};

notes/cloudflare-vs-railway-evaluation.md

···
+# Cloudflare vs Railway: Server Architecture Evaluation
+
+**Date:** 2026-02-02
+**Status:** Research
+**Author:** Architecture Review
+
+---
+
+## Executive Summary
+
+This document evaluates two deployment strategies for the Peek sync server:
+
+1. **Cloudflare Edge Stack**: Workers + Durable Objects + R2
+2. **Railway (Current)**: Full Node.js container with persistent storage
+
+**Recommendation:** Stay on Railway for now, but architect for future portability. The current server is simple enough that Cloudflare migration would add complexity without proportional benefit at current scale. However, if user growth demands global low-latency sync or Railway costs become prohibitive, Cloudflare offers a compelling edge-native model.
+
+---
+
+## Part 1: Cirrus Architecture Summary
+
+### What Cirrus Does
+
+[Cirrus](https://github.com/ascorbic/cirrus) is a single-user AT Protocol Personal Data Server (PDS) optimized for edge deployment. It demonstrates a clean architecture for running per-user SQLite databases on Cloudflare's edge infrastructure.
+
+### Cirrus Architecture
+
+| Component | Role |
+|-----------|------|
+| **Worker** | Stateless edge handler for routing, authentication, DID document serving |
+| **Durable Object** | Single-instance SQLite storage for AT Protocol repository (per user) |
+| **R2** | Object storage for blobs (images, videos) |
+
+### Key Design Decisions
+
+1. **Single-User per Durable Object**: Each user's entire AT Protocol repository lives in one Durable Object. This eliminates distributed consensus complexity - the DO is the authoritative state holder.
+
+2. **Separation of Concerns**:
+   - Structured data (posts, follows, profile) in SQLite within DO
+   - Binary data (images, videos) in R2 object storage
+   - Routing logic in stateless Worker
+
+3. **Edge-Native Authentication**: OAuth 2.1 (PKCE, DPoP, PAR) and passkey support built into the edge layer.
+
+4. **Pay-Per-Use**: Cloudflare's pricing model means costs scale with actual usage rather than reserved capacity.
+
+### What We Can Learn
+
+- **Per-user DO isolation is viable**: One DO per user with embedded SQLite works well for personal data sync.
+- **R2 for blobs**: Keeping binary content out of SQLite simplifies sync and reduces DO storage costs.
+- **Stateless routing layer**: Workers handle auth and routing without maintaining state, making horizontal scaling trivial.
+
+---
+
+## Part 2: Our Current Server Architecture
+
+### Stack
+
+| Component | Technology |
+|-----------|------------|
+| Runtime | Node.js 22+ |
+| Framework | Hono (Express-like, but faster) |
+| Database | SQLite via better-sqlite3 |
+| Deployment | Railway (Nixpacks container) |
+| Storage | Persistent volume at `DATA_DIR` |
+
+### Data Model
+
+```
+data/
+  system.db                  # User registry, profile metadata
+  {userId}/
+    profiles/
+      {profileId}/
+        datastore.sqlite     # Items, tags, item_tags, settings
+        images/
+          {hash}.{ext}       # Deduplicated image files
+```
+
+### Key Components
+
+**`db.js`** - Data Layer (~1100 lines)
+- Connection pool (one SQLite connection per user:profile)
+- Schema migrations with column renames (snake_case to camelCase)
+- Unified `saveItem()` with syncId-based deduplication
+- Soft deletes with `deletedAt` timestamps
+- Image storage with content-hash deduplication
+- Incremental sync via `getItemsSince(timestamp)`
+
+**`users.js`** - Multi-User Auth (~420 lines)
+- SHA-256 hashed API keys in system.db
+- Profile management (UUID-based folder naming)
+- Legacy migration support
+
+**`index.js`** - HTTP API (~770 lines)
+- Hono routes for items, tags, images, profiles, backups
+- Version compatibility middleware (HTTP 409 on mismatch)
+- Auth middleware (Bearer token lookup)
+- Automatic migrations and dedup on startup
+
+### Current Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /items` | Create/update items (sync push) |
+| `GET /items/since/:timestamp` | Incremental pull |
+| `POST /images` | Upload images (multipart or base64) |
+| `GET /images/:id` | Serve image binary |
+| `GET /profiles` | List user profiles |
+| `POST /backups` | Trigger backup |
+
+### Strengths of Current Design
+
+1. **Simple deployment**: Single container, one persistent volume
+2. **Proven stack**: Node.js + SQLite is battle-tested
+3. **Clean data isolation**: Each user/profile has isolated database
+4. **Incremental sync**: `updatedAt`-based change detection works
+5. **Hot reload**: `npm run dev` for local development
+
+### Pain Points
+
+1. **Single region**: Railway hosts in one region; latency for distant users
+2. **Vertical scaling only**: One container handles all users
+3. **Cold starts**: Container can be evicted, slow restart
+4. **Image serving**: Binary files served through Node.js, not CDN
+
+---
+
+## Part 3: What Would Need to Change for Cloudflare
+
+### Architecture Mapping
+
+| Current (Railway) | Cloudflare Equivalent |
+|-------------------|----------------------|
+| Node.js container | Worker (JavaScript runtime) |
+| SQLite file per user | Durable Object with SQLite API |
+| Filesystem images | R2 bucket |
+| Railway volume | Not needed (DO + R2 are persistent) |
+| Single instance | Edge instances globally |
+
+### Required Changes
+
+#### 1. HTTP Framework Migration
+
+```javascript
+// Current: Hono with Node.js adapter
+const { serve } = require("@hono/node-server");
+serve({ fetch: app.fetch, port });
+
+// Cloudflare: Hono runs natively in Workers
+export default app;
+```
+
+Hono already supports Workers natively - this is a minimal change.
+
+#### 2. Database Layer Rewrite
+
+**Current** (better-sqlite3):
+```javascript
+const db = new Database(dbPath);
+db.prepare("SELECT * FROM items WHERE id = ?").get(id);
+```
+
+**Cloudflare** (DO SQLite):
+```javascript
+export class UserStore extends DurableObject {
+  async fetch(request) {
+    const db = this.ctx.storage.sql;
+    const result = db.exec("SELECT * FROM items WHERE id = ?", id);
+    return Response.json(result.toArray());
+  }
+}
+```
+
+**Migration Complexity: HIGH**
+
+- DO's SQLite API is slightly different (D1-style)
+- Connection pool becomes DO instantiation
+- Each request routes to the correct DO by user ID
+- All db.js functions need rewriting
+
+#### 3. Image Storage Migration
+
+**Current**: Filesystem in `data/{userId}/profiles/{profileId}/images/`
+
+**Cloudflare R2**:
+```javascript
+// Upload
+await env.BUCKET.put(`${userId}/${hash}.${ext}`, imageBuffer, {
+  httpMetadata: { contentType: mimeType }
+});
+
+// Serve
+const object = await env.BUCKET.get(`${userId}/${hash}.${ext}`);
+return new Response(object.body, {
+  headers: { 'Content-Type': object.httpMetadata.contentType }
+});
+```
+
+**Migration Complexity: MEDIUM**
+
+- R2 API is straightforward
+- Need to migrate existing images (one-time script)
+- Can serve directly from R2 or through Worker
+
+#### 4. User Registry
+
+**Current**: `system.db` SQLite file shared across all users
+
+**Cloudflare Options**:
+1. **D1**: Cloudflare's managed SQLite (good for small tables)
+2. **KV**: Key-value store (fast lookup by API key hash)
+3. **Dedicated DO**: One DO for user registry
+
+**Recommended**: D1 for user table, or KV for API key -> userId lookup.
+
+#### 5. Routing Layer
+
+Worker needs to:
+1. Authenticate via API key (lookup in D1/KV)
+2. Parse userId from auth
+3. Get/create DO stub for that user
+4. Forward request to DO
+
+```javascript
+export default {
+  async fetch(request, env) {
+    const apiKey = request.headers.get('Authorization')?.slice(7);
+    const userId = await env.USERS.get(hashKey(apiKey));
+    if (!userId) return new Response('Unauthorized', { status: 401 });
+
+    const doId = env.USER_STORES.idFromName(userId);
+    const stub = env.USER_STORES.get(doId);
+    return stub.fetch(request);
+  }
+};
+```
+
+#### 6. Migrations and Schema
+
+DO's SQLite doesn't have automatic migrations. Options:
+- Check schema version on first request, run migrations
+- Use DO's `alarm()` for background migration
+- Store schema version in DO storage
+
+---
+
+## Part 4: Pros and Cons Comparison
+
+### Railway (Current)
+
+| Pros | Cons |
+|------|------|
+| Simple single-container model | Single region (latency for distant users) |
+| Standard Node.js - familiar stack | Vertical scaling only |
+| Filesystem access for images | Cold start after inactivity |
+| Easy local development (`npm run dev`) | Images served through Node.js (not CDN) |
+| Persistent volume (data survives redeploys) | $5/mo minimum even idle |
+| Full npm ecosystem | Container size affects cold start |
+
+**Cost Model**:
+- $5/mo hobby tier (512MB RAM, shared CPU)
+- $20/mo pro for more resources
+- Persistent volumes included
+- Predictable monthly cost
+
+### Cloudflare (Durable Objects + R2)
+
+| Pros | Cons |
+|------|------|
+| Global edge - low latency everywhere | More complex architecture |
+| Per-user isolation via DO | DO's SQLite API differs from better-sqlite3 |
+| R2 + CDN for images | Limited Node.js API compatibility |
+| Auto-scales to zero (pay only for usage) | Debugging is harder (distributed) |
+| No cold start for Workers | 30-second wall-clock limit per request |
+| Built-in DDoS protection | Vendor lock-in (DO is Cloudflare-only) |
+
+**Cost Model**:
+- Workers: 10M free requests/mo, then $0.50/M
+- Durable Objects: $0.15/GB-month storage, $0.50/M requests
+- R2: $0.015/GB-month storage, free egress
+- Could be cheaper at low scale, more expensive at high scale
+
+### Head-to-Head
+
+| Factor | Railway | Cloudflare |
+|--------|---------|------------|
+| **Latency** | Single region (US) | Global edge |
+| **Complexity** | Low | Medium-High |
+| **Migration Effort** | N/A (current) | 2-3 weeks solid work |
+| **Vendor Lock-in** | Low (standard container) | High (Durable Objects) |
+| **Cost at Low Scale** | $5-20/mo fixed | ~$0-5/mo (usage-based) |
+| **Cost at High Scale** | Predictable | Can grow unexpectedly |
+| **Local Dev** | Native Node.js | Wrangler + Miniflare |
+| **Debugging** | Standard logs | Distributed tracing needed |
+| **Image Serving** | Through app | R2 + CDN |
+
+---
+
+## Part 5: Recommendation
+
+### Short-Term (Next 6 Months): Stay on Railway
+
+**Rationale:**
+
+1. **Current scale doesn't justify complexity**: With a handful of users, single-region latency is acceptable.
+
+2. **Development velocity matters more**: Spending 2-3 weeks rewriting for Cloudflare delays features.
+
+3. **Railway is working**: No reported issues with current deployment.
+
+4. **Migration risk**: Cloudflare DO's SQLite API quirks could cause subtle bugs.
+
+### Medium-Term: Architect for Portability
+
+**Actions:**
+
+1. **Abstract the storage layer**: Create a clean interface that could have Railway and Cloudflare implementations.
+
+```javascript
+// storage/interface.js
+export interface StorageBackend {
+  getItem(userId, profileId, itemId): Promise<Item>;
+  saveItem(userId, profileId, item): Promise<string>;
+  getItemsSince(userId, profileId, timestamp): Promise<Item[]>;
+  // ... etc
+}
+```
+
+2. **Move images to R2 now**: Even staying on Railway, images could be served from R2/CDN. This improves latency and reduces server load.
+
+3. **Separate auth from data**: User registry could move to a shared service (D1, Turso, or even Cloudflare KV) while keeping data on Railway.
+
+### Long-Term Triggers for Cloudflare Migration
+
+Migrate when:
+- User count exceeds ~1000 active users
+- Latency complaints from non-US users become frequent
+- Railway costs exceed $50/mo
+- You want to eliminate cold starts for better UX
+
+---
+
+## Part 6: Migration Path (If/When Needed)
+
+### Phase 1: Decouple Images (1 week)
+
+1. Set up R2 bucket
+2. Modify image upload to write to both filesystem and R2
+3. Modify image serving to read from R2
+4. Write migration script for existing images
+5. Deploy, test, then remove filesystem path
+
+### Phase 2: Abstract Storage (1 week)
+
+1. Create `StorageBackend` interface
+2. Implement `RailwayStorageBackend` wrapping current db.js
+3. Refactor index.js to use interface
+4. Test everything still works
+
+### Phase 3: Build Cloudflare Backend (2 weeks)
+
+1. Create `CloudflareStorageBackend` implementing same interface
+2. Build Worker routing layer
+3. Build Durable Object with SQLite schema
+4. Set up local development with Wrangler/Miniflare
+5. Test extensively with synthetic data
+
+### Phase 4: Parallel Run (1 week)
+
+1. Deploy Cloudflare version alongside Railway
+2. Run both in parallel, comparing results
+3. Use feature flag to route percentage of traffic
+4. Monitor for discrepancies
+
+### Phase 5: Cutover (1 day)
+
+1. Put Railway in read-only mode
+2. Migrate any remaining data
+3. Update DNS/client config
+4. Monitor closely for 24 hours
+5. Decommission Railway
+
+### Supporting Both Simultaneously
+
+If you want to support Railway AND Cloudflare (e.g., self-hosted vs managed):
+
+1. Keep both backends in the codebase
+2. Use environment detection to pick backend
+3. Maintain feature parity tests
+4. Document deployment options
+
+---
+
+## Appendix: Reference Links
+
+- [Cirrus GitHub](https://github.com/ascorbic/cirrus)
+- [Cloudflare Durable Objects SQLite](https://developers.cloudflare.com/durable-objects/sqlite/)
+- [Cloudflare R2 Documentation](https://developers.cloudflare.com/r2/)
+- [Railway Persistent Volumes](https://docs.railway.app/reference/volumes)
+- [Hono on Cloudflare Workers](https://hono.dev/docs/getting-started/cloudflare-workers)
+
+---
+
+## Appendix: Cost Modeling
+
+### Scenario: 100 Active Users, 10 syncs/day each
+
+**Railway:**
+- $5/mo hobby tier (probably sufficient)
+- Total: **$5/mo**
+
+**Cloudflare:**
+- Workers: 100 * 10 * 30 = 30,000 requests/mo (free tier)
+- DO: 100 users * ~1MB each = 100MB storage ($0.015/mo) + 30,000 requests ($0.015)
+- R2: 100 users * 50MB images = 5GB ($0.075/mo)
+- Total: **~$0.10/mo**
+
+### Scenario: 10,000 Active Users, 10 syncs/day each
+
+**Railway:**
+- $20/mo pro tier
+- May need vertical scaling
+- Total: **$20-50/mo**
+
+**Cloudflare:**
+- Workers: 3M requests/mo (free tier covers)
+- DO: 10GB storage ($1.50) + 3M requests ($1.50)
+- R2: 500GB images ($7.50/mo)
+- Total: **~$10-15/mo**
+
+**Conclusion**: Cloudflare is cheaper at scale, Railway is simpler at small scale.

notes/server-portability-plan.md

···
+# Server Portability Plan
+
+## Executive Summary
+
+This plan covers three architectural changes to make the Peek server portable across different hosting environments:
+
+1. **SQL Abstraction Layer** - Abstract `better-sqlite3` to support Cloudflare Durable Objects SQLite API
+2. **Image Storage Abstraction** - Abstract filesystem storage to support R2/S3
+3. **User Registry Decoupling** - Enable single-user mode for simplified self-hosting
+
+---
+
+## Current Architecture Analysis
+
+### Database Layer (`backend/server/db.js`)
+
+**SQLite-specific APIs currently used:**
+
+| API | Usage |
+|-----|-------|
+| `new Database(path)` | Connection creation |
+| `db.pragma("journal_mode = WAL")` | Write-ahead logging |
+| `db.exec(sql)` | DDL and multi-statement execution |
+| `db.prepare(sql).run(...)` | Parameterized writes |
+| `db.prepare(sql).get(...)` | Single row reads |
+| `db.prepare(sql).all(...)` | Multi-row reads |
+| `db.transaction(fn)()` | Atomic table rebuilds |
+
+**Connection pool pattern:**
+```javascript
+const connections = new Map();  // keyed by `${userId}:${profileId}`
+```
+
+**Path structure:**
+```
+DATA_DIR/{userId}/profiles/{profileId}/datastore.sqlite
+```
+
+### User Registry (`backend/server/users.js`)
+
+- Separate `system.db` at `DATA_DIR/system.db`
+- Tables: `users` (id, api_key_hash, created_at) and `profiles` (id, user_id, slug, name, ...)
+- API key auth: SHA-256 hash lookup
+- Profile resolution handles both UUIDs and legacy slugs
+
+### Image Storage (`backend/server/db.js`)
+
+- Filesystem path: `DATA_DIR/{userId}/profiles/{profileId}/images/`
+- Content-hash deduplication: files named `{sha256}.{ext}`
+- Metadata in `items` table (type='image', metadata JSON with hash/mime/size)
+- Functions: `saveImage`, `getImagePath`, `getUserImagesDir`
+
+---
+
+## 1. SQL Abstraction Layer
+
+### Proposed Interface
+
+```typescript
+// backend/server/sql/types.ts
+
+interface RunResult {
+  changes: number;
+  lastInsertRowid?: number;
+}
+
+interface SqlAdapter {
+  // Core query methods
+  exec(sql: string): void;
+  run(sql: string, params?: unknown[]): RunResult;
+  get<T = unknown>(sql: string, params?: unknown[]): T | null;
+  all<T = unknown>(sql: string, params?: unknown[]): T[];
+
+  // Transaction support
+  transaction<T>(fn: () => T): T;
+
+  // Lifecycle
+  close(): void;
+}
+
+interface SqlAdapterFactory {
+  open(path: string, options?: { readonly?: boolean }): SqlAdapter;
+  init(adapter: SqlAdapter): void;  // Platform-specific setup (WAL mode)
+}
+```
+
+### better-sqlite3 Adapter Implementation
+
+```typescript
+// backend/server/sql/better-sqlite3-adapter.ts
+
+import Database from 'better-sqlite3';
+import type { SqlAdapter, SqlAdapterFactory, RunResult } from './types';
+
+class BetterSqlite3Adapter implements SqlAdapter {
+  private db: Database.Database;
+  private stmtCache = new Map<string, Database.Statement>();
+
+  constructor(db: Database.Database) {
+    this.db = db;
+  }
+
+  exec(sql: string): void {
+    this.db.exec(sql);
+  }
+
+  run(sql: string, params: unknown[] = []): RunResult {
+    const stmt = this.getOrPrepare(sql);
+    const result = stmt.run(...params);
+    return { changes: result.changes, lastInsertRowid: Number(result.lastInsertRowid) };
+  }
+
+  get<T>(sql: string, params: unknown[] = []): T | null {
+    return (this.getOrPrepare(sql).get(...params) as T) ?? null;
+  }
+
+  all<T>(sql: string, params: unknown[] = []): T[] {
+    return this.getOrPrepare(sql).all(...params) as T[];
+  }
+
+  transaction<T>(fn: () => T): T {
+    return this.db.transaction(fn)();
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  private getOrPrepare(sql: string): Database.Statement {
+    let stmt = this.stmtCache.get(sql);
+    if (!stmt) {
+      stmt = this.db.prepare(sql);
+      this.stmtCache.set(sql, stmt);
+    }
+    return stmt;
+  }
+}
+
+export const factory: SqlAdapterFactory = {
+  open(path: string): SqlAdapter {
+    return new BetterSqlite3Adapter(new Database(path));
+  },
+  init(adapter: SqlAdapter): void {
+    adapter.exec("PRAGMA journal_mode = WAL");
+  }
+};
+```
+
+### Cloudflare DO SQLite Adapter
+
+```typescript
+// backend/server/sql/do-sqlite-adapter.ts
+
+import type { SqlAdapter, RunResult } from './types';
+
+class DoSqliteAdapter implements SqlAdapter {
+  private sql: SqlStorage;
+
+  constructor(storage: SqlStorage) {
+    this.sql = storage;
+  }
+
+  exec(sql: string): void {
+    this.sql.exec(sql);
+  }
+
+  run(sql: string, params: unknown[] = []): RunResult {
+    const cursor = this.sql.exec(sql, ...params);
+    return { changes: cursor.rowsWritten, lastInsertRowid: cursor.lastRowId };
+  }
+
+  get<T>(sql: string, params: unknown[] = []): T | null {
+    const rows = this.sql.exec(sql, ...params).toArray();
+    return rows.length > 0 ? (rows[0] as T) : null;
+  }
+
+  all<T>(sql: string, params: unknown[] = []): T[] {
+    return this.sql.exec(sql, ...params).toArray() as T[];
+  }
+
+  transaction<T>(fn: () => T): T {
+    return fn();  // DO transactions are implicit
+  }
+
+  close(): void {
+    // No-op for DO
+  }
+}
+
+export function createFromStorage(storage: SqlStorage): SqlAdapter {
+  return new DoSqliteAdapter(storage);
+}
+```
+
+### Migration Strategy for db.js
+
+**Before (current):**
+```javascript
+const db = new Database(dbPath);
+db.pragma("journal_mode = WAL");
+db.exec(`CREATE TABLE IF NOT EXISTS items (...)`);
+const row = db.prepare("SELECT id FROM items WHERE id = ?").get(id);
+db.prepare("INSERT INTO items (...) VALUES (...)").run(v1, v2, v3);
+```
+
+**After (with adapter):**
+```javascript
+const adapter = factory.open(dbPath);
+factory.init(adapter);
+adapter.exec(`CREATE TABLE IF NOT EXISTS items (...)`);
+const row = adapter.get("SELECT id FROM items WHERE id = ?", [id]);
+adapter.run("INSERT INTO items (...) VALUES (?, ?, ?)", [v1, v2, v3]);
+```
+
+### Files to Create/Modify
+
+| File | Action | Notes |
+|------|--------|-------|
+| `backend/server/sql/types.ts` | Create | Interface definitions |
+| `backend/server/sql/better-sqlite3-adapter.ts` | Create | Current platform adapter |
+| `backend/server/sql/do-sqlite-adapter.ts` | Create | Cloudflare adapter (future) |
+| `backend/server/sql/index.ts` | Create | Factory selection based on config |
+| `backend/server/db.js` | Modify | Replace 50+ direct better-sqlite3 calls |
+| `backend/server/users.js` | Modify | Replace 15+ direct calls for system.db |
+| `backend/server/backup.js` | Modify | Handle `VACUUM INTO` (not available on DO) |
+
+---
+
+## 2. Image Storage Abstraction
+
+### Proposed Interface
+
+```typescript
+// backend/server/storage/types.ts
+
+interface StorageAdapter {
+  put(key: string, data: Buffer, metadata?: Record<string, string>): Promise<void>;
+  get(key: string): Promise<Buffer | null>;
+  delete(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+  list(prefix?: string): Promise<string[]>;
+}
+
+interface StorageConfig {
+  type: 'filesystem' | 'r2' | 's3';
+  // Filesystem
+  basePath?: string;
+  // R2/S3
+  bucket?: string;
+  region?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  endpoint?: string;
+}
+```
+
+### Filesystem Adapter
+
+```typescript
+// backend/server/storage/filesystem-adapter.ts
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { StorageAdapter } from './types';
+
+export class FilesystemAdapter implements StorageAdapter {
+  constructor(private basePath: string) {}
+
+  async put(key: string, data: Buffer): Promise<void> {
+    const fullPath = path.join(this.basePath, key);
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    if (!fs.existsSync(fullPath)) fs.writeFileSync(fullPath, data);  // Dedup
+  }
+
+  async get(key: string): Promise<Buffer | null> {
+    const fullPath = path.join(this.basePath, key);
+    return fs.existsSync(fullPath) ? fs.readFileSync(fullPath) : null;
+  }
+
+  async delete(key: string): Promise<void> {
+    const fullPath = path.join(this.basePath, key);
+    if (fs.existsSync(fullPath)) fs.unlinkSync(fullPath);
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return fs.existsSync(path.join(this.basePath, key));
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    // Recursive directory walk
+  }
+}
+```
+
+### R2 Adapter (for Workers)
+
+```typescript
+// backend/server/storage/r2-adapter.ts
+
+import type { StorageAdapter } from './types';
+
+export class R2Adapter implements StorageAdapter {
+  constructor(private bucket: R2Bucket) {}
+
+  async put(key: string, data: Buffer, metadata?: Record<string, string>): Promise<void> {
+    await this.bucket.put(key, data, { customMetadata: metadata });
+  }
+
+  async get(key: string): Promise<Buffer | null> {
+    const obj = await this.bucket.get(key);
+    return obj ? Buffer.from(await obj.arrayBuffer()) : null;
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.bucket.delete(key);
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return (await this.bucket.head(key)) !== null;
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    const results: string[] = [];
+    let cursor: string | undefined;
+    do {
+      const resp = await this.bucket.list({ prefix, cursor });
+      results.push(...resp.objects.map(o => o.key));
+      cursor = resp.truncated ? resp.cursor : undefined;
+    } while (cursor);
+    return results;
+  }
+}
+```
+
+### Key Format
+
+Storage key format:
+```
+{userId}/{profileId}/images/{hash}.{ext}
+```
+
+### Files to Create/Modify
+
+| File | Action |
+|------|--------|
+| `backend/server/storage/types.ts` | Create |
+| `backend/server/storage/filesystem-adapter.ts` | Create |
+| `backend/server/storage/r2-adapter.ts` | Create |
+| `backend/server/storage/s3-adapter.ts` | Create (optional) |
+| `backend/server/storage/index.ts` | Create (factory) |
+| `backend/server/db.js` | Modify (saveImage, getImagePath) |
+| `backend/server/index.js` | Modify (image serving) |
+
+---
+
+## 3. User Registry Decoupling
+
+### Single-User Mode Design
+
+```typescript
+// backend/server/config.ts
+
+interface ServerConfig {
+  mode: 'multi-user' | 'single-user';
+  singleUser?: {
+    userId: string;      // default: "default"
+    token?: string;      // optional bearer token
+  };
+}
+
+export function loadConfig(): ServerConfig {
+  if (process.env.SINGLE_USER_MODE === 'true') {
+    return {
+      mode: 'single-user',
+      singleUser: {
+        userId: process.env.SINGLE_USER_ID || 'default',
+        token: process.env.SINGLE_USER_TOKEN
+      }
+    };
+  }
+  return { mode: 'multi-user' };
+}
+```
+
+### Auth Middleware Factory
+
+```typescript
+// backend/server/auth.ts
+
+export function createAuthMiddleware(config: ServerConfig) {
+  if (config.mode === 'single-user') {
+    return singleUserMiddleware(config.singleUser!);
+  }
+  return multiUserMiddleware();
+}
+
+function singleUserMiddleware({ userId, token }) {
+  return async (c, next) => {
+    if (c.req.path === '/') return next();
+
+    if (token) {
+      const auth = c.req.header('Authorization');
+      if (!auth || auth !== `Bearer ${token}`) {
+        return c.json({ error: 'Unauthorized' }, 401);
+      }
+    }
+
+    c.set('userId', userId);
+    return next();
+  };
+}
+```
+
+### Path Simplification in Single-User Mode
+
+**Multi-user (current):**
+```
+DATA_DIR/
+├── system.db
+├── {userId}/
+│   └── profiles/
+│       └── {profileId}/
+│           ├── datastore.sqlite
+│           └── images/
+```
+
+**Single-user:**
+```
+DATA_DIR/
+├── profiles/
+│   └── {profileId}/
+│       ├── datastore.sqlite
+│       └── images/
+```
+
+### Config Flag Behavior
+
+| Config | system.db | User lookup | Path prefix |
+|--------|-----------|-------------|-------------|
+| `SINGLE_USER_MODE=false` | Required | API key hash | `{userId}/profiles/{profileId}` |
+| `SINGLE_USER_MODE=true` | Not created | Skip | `profiles/{profileId}` |
+
+### Files to Create/Modify
+
+| File | Action |
+|------|--------|
+| `backend/server/config.ts` | Create |
+| `backend/server/auth.ts` | Create |
+| `backend/server/index.js` | Modify (use auth factory) |
+| `backend/server/db.js` | Modify (getConnection path logic) |
+| `backend/server/backup.js` | Modify (single-user backup path) |
+
+---
+
+## Implementation Order
+
+### Phase 1: SQL Abstraction
+1. Create `sql/` directory with types and adapters
+2. Refactor `db.js` incrementally (keep tests passing)
+3. Refactor `users.js`
+4. Refactor `backup.js`
+5. All existing tests must pass
+
+### Phase 2: Storage Abstraction
+1. Create `storage/` directory with adapters
+2. Add `getImageKey()` helper to db.js
+3. Refactor `saveImage()` to use storage adapter
+4. Refactor image serving in `index.js`
+5. Test with filesystem adapter (identical behavior)
+
+### Phase 3: User Registry Decoupling
+1. Create `config.ts` and `auth.ts`
+2. Modify `index.js` to use auth middleware factory
+3. Add path logic for single-user mode in `db.js`
+4. Test single-user mode end-to-end
+5. Update documentation
+
+---
+
+## Testing Approach
+
+### Unit Tests (New)
+
+```javascript
+// sql/better-sqlite3-adapter.test.js
+describe('BetterSqlite3Adapter', () => {
+  it('exec() runs DDL', () => {});
+  it('run() returns changes count', () => {});
+  it('get() returns single row or null', () => {});
+  it('all() returns array', () => {});
+  it('transaction() is atomic', () => {});
+});
+```
+
+### Integration Tests (Existing)
+
+All 92 existing tests in `backend/server/test.js` must pass after each phase.
+
+---
+
+## Configuration Summary
+
+```bash
+# Current (multi-user, filesystem)
+# No changes needed
+
+# Single-user mode
+SINGLE_USER_MODE=true
+SINGLE_USER_TOKEN=secret-token  # Optional
+
+# Future: R2 storage
+STORAGE_BACKEND=r2
+R2_BUCKET=peek-images
+
+# Future: DO SQLite (Cloudflare Workers only)
+SQL_ADAPTER=do-sqlite
+```
+
+---
+
+## Resolved Questions
+
+1. **Backup with DO SQLite**: `VACUUM INTO` not available. Export to R2 as JSON?
+   - **Answer**: Yes, but just add a TODO for now - not deploying to Cloudflare yet.
+
+2. **Image URLs**: Direct R2 URLs or proxy through worker?
+   - **Answer**: Put hash in URL so we can easily switch between backends later.
+
+3. **Profiles in single-user**: Keep for workspaces or remove entirely?
+   - **Answer**: Single-user will always have profiles - only removing multi-user from the base.
+
+4. **Migration path**: How to migrate existing multi-user data to single-user?
+   - **Answer**: Only one real user currently. At deployment time, find the one active account and migrate by uplifting one dir into another.

schema/generated/sqlite-full.sql

···
 -- Generated by schema/codegen.js
 -- Schema version: 1
--- Generated: 2026-02-01T23:03:47.198Z
+-- Generated: 2026-02-02T08:01:19.478Z
 -- DO NOT EDIT - regenerate with: yarn schema:codegen
 
 -- Unified content storage - URLs, text notes, tagsets, and images

schema/generated/sqlite-sync.sql

···
 -- Generated by schema/codegen.js
 -- Schema version: 1
--- Generated: 2026-02-01T23:03:47.198Z
+-- Generated: 2026-02-02T08:01:19.479Z
 -- DO NOT EDIT - regenerate with: yarn schema:codegen
 
 -- Unified content storage - URLs, text notes, tagsets, and images

schema/generated/types.rs

···
 // Generated by schema/codegen.js
 // Schema version: 1
-// Generated: 2026-02-01T23:03:47.199Z
+// Generated: 2026-02-02T08:01:19.479Z
 // DO NOT EDIT - regenerate with: yarn schema:codegen
 
 use serde::{Deserialize, Serialize};

schema/generated/types.ts

···
 /**
  * Generated by schema/codegen.js
  * Schema version: 1
- * Generated: 2026-02-01T23:03:47.199Z
+ * Generated: 2026-02-02T08:01:19.479Z
  * DO NOT EDIT - regenerate with: yarn schema:codegen
  */