init

NOTES.md

@@ -0,0 +1,335 @@
+# Viewer — Final Design (Go + TypeScript)
+
+## 1. Goals
+
+1. View a large personal photo archive organized as **ZIP albums** (≈10k ZIPs, ~20 photos each).
+2. Keep storage efficient on a **home S3-compatible server** that performs poorly with many small objects.
+3. Provide a **photo-centric UI** with:
+   - **Page 1:** Random “Pinterest-like” wall (edge-to-edge)
+   - **Page 2:** Full-screen album viewer (edge-to-edge)
+4. Avoid a database. Use **S3 as source of truth** + **one metadata JSON per ZIP**.
+
+## 2. Non-Goals (for MVP)
+
+- Search, tagging, ML classification
+- Sharing/auth beyond minimal single-user auth
+- Full offline indexing of every photo ahead of time
+- Generating/storing per-photo thumbnails as separate S3 objects
+
+------
+
+## 3. High-Level Architecture
+
+### Components
+
+1. **Web Frontend (TypeScript)**
+   - Upload ZIP
+   - Page 1 random wall
+   - Page 2 full-screen viewer
+2. **API Server (Go)**
+   - Album upload session + finalize
+   - Generate and store album metadata JSON
+   - Random feed API
+   - Image serving API (extract from ZIP; optional resize/caching)
+3. **S3-Compatible Storage (Home Server)**
+   - Stores ZIP objects (large, few)
+   - Stores per-album `index.json` (small, few)
+4. **Optional Local Disk Cache (API Server)**
+   - Cache resized images and/or extracted bytes to reduce repeated ZIP work
+
+------
+
+## 4. Storage Layout (S3 Keys)
+
+Bucket: `photo-archive`
+
+For each album (`albumId` is a UUID or content-hash):
+
+- Source ZIP (1 object):
+  - `albums/{albumId}/source.zip`
+- Album metadata (1 object):
+  - `albums/{albumId}/index.json`
+
+No per-photo thumbnail objects in S3.
+
+------
+
+## 5. Album Metadata Format (`index.json`)
+
+Purpose:
+
+- Allow the UI and APIs to:
+  - list photos in order
+  - compute masonry layout using aspect ratio
+  - address a photo by `(albumId, photoIndex)`
+
+Example:
+
+```json
+{
+  "albumId": "a1b2c3...",
+  "originalFilename": "2021_trip.zip",
+  "createdAt": "2026-02-13T00:00:00Z",
+  "photoCount": 20,
+  "photos": [
+    {
+      "i": 0,
+      "name": "IMG_0001.JPG",
+      "w": 4032,
+      "h": 3024,
+      "ratio": 1.3333
+    }
+  ]
+}
+```
+
+Notes:
+
+- `i` is the stable ordering index (sort by filename or ZIP entry order; pick one and keep it consistent).
+- Width/height are extracted from image headers (or by decoding if needed).
+
+------
+
+## 6. Core APIs
+
+### 6.1 Create Album Upload Session
+
+```
+POST /api/albums
+```
+
+Request:
+
+```json
+{ "filename": "my_album.zip", "sizeBytes": 123456789 }
+```
+
+Response:
+
+```json
+{
+  "albumId": "uuid-or-hash",
+  "upload": {
+    "method": "PUT",
+    "url": "presigned-url",
+    "headers": { }
+  }
+}
+```
+
+Behavior:
+
+- Server decides `albumId`.
+- Server returns a presigned PUT URL to upload `albums/{albumId}/source.zip`.
+
+### 6.2 Finalize Upload (Trigger Metadata Generation)
+
+```
+POST /api/albums/{albumId}/finalize
+```
+
+Response:
+
+```json
+{ "status": "INDEXING" }
+```
+
+Behavior:
+
+- Server verifies ZIP exists in S3.
+- Server builds `albums/{albumId}/index.json`.
+- For MVP: do it synchronously (may take seconds). Optionally return early and allow polling.
+
+### 6.3 Get Album Metadata
+
+```
+GET /api/albums/{albumId}
+```
+
+Response: the `index.json` content.
+
+### 6.4 List Albums (Lightweight)
+
+```
+GET /api/albums
+```
+
+Response:
+
+```json
+{
+  "albums": [
+    { "albumId": "...", "photoCount": 20, "originalFilename": "..." }
+  ]
+}
+```
+
+Implementation:
+
+- List `albums/*/index.json` objects (or list `albums/` prefixes and fetch index.json per album; cache results server-side).
+
+### 6.5 Random Feed (Page 1)
+
+```
+GET /api/feed?limit=80&seed=abc&cursor=...
+```
+
+Response:
+
+```json
+{
+  "items": [
+    {
+      "albumId": "....",
+      "i": 7,
+      "w": 4032,
+      "h": 3024,
+      "ratio": 1.3333,
+      "src": "/api/image/a1b2c3/7?mode=wall&w=480"
+    }
+  ],
+  "nextCursor": "..."
+}
+```
+
+Behavior:
+
+- Randomly sample `(albumId, photoIndex)` pairs from existing albums.
+- Returns enough metadata for masonry and a URL to request the image bytes.
+- Server can cache album indices in memory for speed.
+
+### 6.6 Serve Image Bytes (On-demand)
+
+`GET /api/image/{albumId}/{i}?mode=wall&w=480`
+`GET /api/image/{albumId}/{i}?mode=viewer&max=0`
+
+Modes:
+
+- `wall`:
+  - Return a resized image suitable for the wall (e.g., width=480).
+- `viewer`:
+  - Return the original (or optionally a large “fit” size).
+
+Caching (optional but recommended):
+
+- Disk cache key:
+  - `cache/{albumId}/{i}/wall_{w}.jpg`
+  - `cache/{albumId}/{i}/viewer_orig.jpg` (or `viewer_{max}.jpg`)
+
+------
+
+## 7. ZIP Indexing Strategy
+
+### 7.1 Minimal Indexing (MVP)
+
+When `/finalize` is called:
+
+1. Download ZIP to local temp **or** read via Range (optional optimization).
+2. Enumerate entries; keep only `.jpg/.jpeg/.png`.
+3. Determine ordering (e.g., filename sort).
+4. Extract width/height for each entry:
+   - Prefer header parsing or minimal decode.
+5. Write `index.json` to S3.
+
+ZIP format note:
+
+- Many implementations locate the “central directory” at the end of the ZIP to enumerate entries efficiently, which can enable Range-based partial reads. ([Rhardih](https://rhardih.io/tag/zip/?utm_source=chatgpt.com))
+
+### 7.2 Range-based ZIP Reading (Optional Optimization)
+
+If the home S3 server supports HTTP Range well:
+
+- Fetch the last chunk to find the End-of-Central-Directory
+- Fetch the central directory region
+- Fetch only the bytes for requested entries
+
+This can avoid full ZIP downloads, but is not required for MVP.
+
+------
+
+## 8. UI Specification (Photo-first, Edge-to-Edge)
+
+### 8.1 Page 1 — Random Wall (Immersive Masonry)
+
+Principles:
+
+- **No padding**. Content is edge-to-edge.
+- Minimal UI overlays.
+- Main action is scrolling and tapping photos.
+
+Layout:
+
+- Masonry/columns layout
+- Gap: `0` (or extremely small if needed)
+- Infinite scroll; loads next batch from `/api/feed`
+
+Controls:
+
+- **Bottom floating control bar** (safe-area aware), auto-hide on scroll:
+  - Column selector: `1 | 2 | 3 | 4` (single tap)
+  - Upload: `+`
+
+Interaction:
+
+- Tap photo -> navigate to Page 2:
+  - Route: `/album/{albumId}?i={photoIndex}`
+
+### 8.2 Page 2 — Album Viewer (Full-screen)
+
+Principles:
+
+- **One photo per screen**, edge-to-edge.
+- Default fit mode: **cover** (fills screen; cropping allowed).
+- Single tap toggles UI overlays.
+
+Gestures:
+
+- Swipe left/right: previous/next photo
+- Swipe down: close (return to wall, restore scroll position)
+- Pinch zoom: optional (if implemented)
+
+Overlays (shown only when toggled on):
+
+- Top: close/back + `currentIndex / total`
+- Bottom: minimal progress indicator (optional)
+
+------
+
+## 9. Performance Strategy (No Small S3 Objects)
+
+- Store only:
+  - **1 ZIP object per album**
+  - **1 JSON index per album**
+- Avoid storing thumbnails per photo in S3.
+- Optional server disk cache for resized images:
+  - Improves repeated viewing without adding S3 objects.
+- Server should cache `index.json` in memory to avoid repeated S3 reads.
+
+------
+
+## 10. Error Handling & Edge Cases
+
+- ZIP contains non-images: ignore.
+- Corrupt image: skip entry; record count accordingly.
+- Empty album after filtering: mark finalize as failed (return error).
+- Large ZIP: enforce max size and timeouts.
+- Security:
+  - Validate ZIP entry names (prevent path traversal if extracting)
+  - Enforce allowed extensions and content-type sniffing
+
+------
+
+## 11. Implementation Milestones (Codex Task Breakdown)
+
+1. **Backend**
+   - S3 client, presigned PUT, upload finalize
+   - ZIP indexing -> generate `index.json` -> put to S3
+   - `/feed` sampling using cached indices
+   - `/image/:albumId/:i` serving + optional resize + optional disk cache
+2. **Frontend**
+   - Upload flow (select ZIP -> upload -> finalize -> ready)
+   - Page 1 masonry wall (edge-to-edge) + infinite scroll + bottom bar
+   - Page 2 full-screen viewer + swipe navigation + UI toggle + close restore
+3. **Polish**
+   - Caching, better error states, basic metrics/logging
+