deckyvault/docs/2025-05-05-sync-pwa-architectural-spec.md

# Architectural Spec: Sync Unification, Nav Cleanup & PWA

**Date:** 2025-05-05
**Status:** Draft — Awaiting Tactical Planning
**Author:** Autonomous Architect

---

## 1. Problem Statement

Three distinct objectives converge on a single architectural concern: **data integrity through pipeline unification**. The remaining objectives (nav removal, PWA) are scoped-down implementation tasks that share no domain coupling with the sync work.

### 1.1 Observed Symptoms

| Symptom | Root Cause |
|---|---|
| Steam review scores missing after initial game insert | Two separate code paths insert games; only one fetches review data |
| Review data appears only after manual sync from `/manage` | Manual sync uses the complete `syncSteamGame` pipeline; initial insert does not |
| Playability status not recalculated on initial insert | `recalculatePlayability` is called only in `syncSteamGame`, not in stub creation |

### 1.2 Three Divergent Sync Paths

**Path A — Initial Insert (two locations):**
- `lib/api/game-stub.ts` → `/games/stub` (Elysia API route)
- `app/game/[id]/page.tsx` → `createGameStub()` (Next.js server component)
- Fetches Steam API directly, inserts game row, returns
- **Missing**: `steamReviewScore`, `steamReviewSentiment`, `steamReviewCount`, `recalculatePlayability` call, error tracking fields (`syncRetryCount`, `syncNextRetry`, `syncError`)

**Path B — Stale-While-Revalidate Auto-Sync:**
- `app/game/[id]/page.tsx` → calls `syncSteamGame()`
- `app/games/page.tsx` → calls `syncSteamGame()`
- Uses full pipeline: Steam API + reviews + playability + error tracking

**Path C — Manual Dashboard Sync:**
- `lib/api/games.ts` → `gameSyncRoutes` → `POST /games/:gameId/sync`
- Uses same `syncSteamGame()` as Path B

**Conclusion**: Paths B and C are identical. Path A diverges entirely.

---

## 2. Architecture Boundaries

### 2.1 Source of Truth

`syncSteamGame(steamAppId: number)` in `lib/steam/sync.ts` is the **single canonical sync pipeline**. Every code path that creates or updates a Steam game's data MUST route through this function.

### 2.2 Forbidden Patterns

- No direct `fetch("https://store.steampowered.com/api/appdetails/...")` calls outside of `lib/steam/sync.ts`
- No manual `db.insert(games)` or `db.update(games)` for Steam-sourced games that populates fields covered by `syncSteamGame`
- No duplicate field-mapping logic between Steam API response and DB schema

### 2.3 Allowed Extensions

- `syncSteamGame` may be extended with new fields (e.g., Steam Deck verification status)
- Wrapper functions may call `syncSteamGame` with pre/post hooks (e.g., batch sync with progress reporting)
- The stub-creation flow may insert a **minimal stub** (appId + title only) and then delegate to `syncSteamGame` for full population

---

## 3. Sync Unification Design

### 3.1 Two-Stage Insert Pattern

For initial game creation, use a **stub-then-sync** pattern:

```
User provides steamAppId
    │
    ▼
┌─────────────────────────────┐
│ 1. Check if exists          │
│    (by steamAppId)          │
│    ├─ Exists → return       │
│    └─ New → continue        │
├─────────────────────────────┤
│ 2. Insert MINIMAL stub      │
│    Fields: steamAppId,      │
│    source="steam",          │
│    title (placeholder),     │
│    syncStatus="pending"     │
├─────────────────────────────┤
│ 3. Call syncSteamGame()     │
│    Populates ALL fields:    │
│    title, developer,        │
│    publisher, description,  │
│    genres, images, prices,  │
│    metacritic, reviews,     │
│    platforms, requirements, │
│    categories, releaseDate, │
│    lastSync, syncStatus,    │
│    error tracking           │
├─────────────────────────────┤
│ 4. recalculatePlayability() │
│    (called inside           │
│     syncSteamGame)          │
├─────────────────────────────┤
│ 5. Return complete game     │
└─────────────────────────────┘
```

### 3.2 Affected Files

| File | Change |
|---|---|
| `lib/api/game-stub.ts` | Replace direct Steam fetch + insert with stub insert → `syncSteamGame` call |
| `app/game/[id]/page.tsx` `createGameStub()` | Same refactor; delegate to `syncSteamGame` after minimal stub insert |
| `lib/steam/sync.ts` `syncSteamGame()` | Verify it handles the case where a game row exists but has only stub fields (idempotent update) — current implementation uses `db.update()` so it already requires the row to exist. This is correct for the two-stage pattern. |

### 3.3 Error Semantics

- **Stub insert failure**: Return 500 immediately — database is unreachable
- **Sync failure after stub exists**: The stub persists with `syncStatus="error"` and `syncError` populated. The game page renders with partial data. Retry is governed by exponential backoff in `recordSyncFailure`.
- **Type rejection** (e.g., DLC, soundtrack): The stub should not be inserted. Validate type before inserting the stub, or insert the stub and let `syncSteamGame` mark it as errored (prefer validating upfront to avoid dead rows).

### 3.4 Validation Checklist

After unification, verify:
- [ ] New game insert via search: `steamReviewScore` is populated immediately
- [ ] New game insert via direct URL: `steamReviewScore` is populated immediately
- [ ] Existing stale game visited after 7+ days: auto-sync refreshes all fields
- [ ] Manual sync from `/manage`: no regression (already uses `syncSteamGame`)
- [ ] Non-game Steam IDs (DLC, demos) are rejected before stub creation
- [ ] Playability is recalculated on every sync (insert or update)

---

## 4. Navbar: Remove "Updates"

### 4.1 Scope

Single-file change. No cascading impacts.

### 4.2 Affected Files

| File | Change |
|---|---|
| `lib/routes.ts` | Remove the `{ title: "Updates", href: "/updates" }` entry from the `routes` array |

### 4.3 Considerations

- The `/updates` page directory (`app/updates/`) may remain on disk (dead code). Can be removed in a separate cleanup pass. Priority: remove nav entry immediately.
- No import references to check — `routes` is consumed only by `components/navbar.tsx` and the mobile sidebar, both of which iterate `routes` dynamically.

---

## 5. PWA & Steam Deck UX

### 5.1 Current State

- ✅ Web manifest exists (`app/manifest.ts`) with `display: "standalone"`, theme color, icons
- ❌ No service worker registered — zero offline capability
- ❌ No touch-optimized interactions (hover-dependent UI elements)
- ❌ No gamepad navigation support
- ❌ No `viewport` meta with `user-scalable=no` for installed PWA feel
- ✅ `next.config.ts` has remote image patterns configured (Steam CDN, SteamGridDB)

### 5.2 Design Decisions (Deferred to Tactical Planning)

These require explicit user input — the following are **constraints**, not implementation details:

#### 5.2.1 Offline Strategy

**Constraint**: Must use Workbox or next-pwa for service worker generation. The SW must:
- Precache the app shell (layout, navbar, CSS, fonts)
- Cache game pages on first visit (stale-while-revalidate for HTML, cache-first for images from Steam CDN)
- Cache API responses from the Elysia backend for a short TTL (5 minutes for listings, 1 hour for game details)
- Provide a "You're offline" fallback UI when uncached pages are requested

**Open question**: Should offline mode show a curated "previously viewed" list, or a generic offline message?

#### 5.2.2 Touch Optimization

**Constraint**: All interactive elements must meet a minimum 44×44px touch target (WCAG 2.1 AA). Specific areas:
- Navbar links and hamburger menu
- Game card tap targets (currently `Link` wrapping entire card — verify touch area)
- Filter controls on `/games` (chips, dropdowns)
- Comment submission buttons
- Profile/settings forms

**Open question**: Should touch optimization include a dedicated "Deck Mode" layout toggle, or be applied universally as responsive CSS?

#### 5.2.3 Gamepad Navigation

**Constraint**: Use the Gamepad API (`navigator.getGamepads()`). Implementation must:
- Map D-pad/left stick to focus navigation (roving tabindex)
- Map A button to `click()` on focused element
- Map B button to browser back
- Map L1/R1 (bumpers) to tab switching on game pages
- Provide a visual focus ring distinct from `:focus-visible` so mouse users aren't affected
- Only activate when a gamepad input is detected (not on page load)
- Disable when mouse/keyboard input is detected (reclaim interaction)

**Open question**: Should gamepad support be a global utility hook or scoped to the game detail page only?

### 5.3 PWA Technical Boundaries

- Service worker must NOT cache authenticated pages (profile, manage) — these require live data
- Service worker must NOT cache POST/PATCH/DELETE API responses
- The `manifest.ts` must be updated with proper icon sizes (192px maskable, 512px)
- A `viewport` meta tag must be set in `layout.tsx`: `content="width=device-width, initial-scale=1, viewport-fit=cover"`

---

## 6. Security & Data Integrity Constraints

### 6.1 Steam API Keys

- The Steam Web API key (for reviews) is called server-side only in `syncSteamGame`. No client-side exposure risk.
- The SteamGridDB API key is also server-side only. No change needed.

### 6.2 Rate Limiting

- `syncSteamGame` already has 15s timeout on Steam API calls
- Batch sync in `/manage` has 1.5s inter-request delay
- The background sync in `games/page.tsx` also has 1.5s delay
- **Constraint**: The stub-then-sync pattern must not introduce new burst traffic. Single-game insert is inherently rate-limit-safe (one request per user action).

### 6.3 Database Integrity

- `steamAppId` has a UNIQUE constraint — prevents duplicate stubs
- `syncSteamGame` uses `db.update().where(eq(games.steamAppId, ...))` — safe for re-entry
- **Risk**: If two requests race to create a stub for the same appId, one will fail on UNIQUE constraint. The loser must gracefully return the existing game.

---

## 7. Scope Boundaries

### In Scope
1. Unify initial insert to use `syncSteamGame` pipeline (2 code locations)
2. Remove "Updates" from `lib/routes.ts`
3. PWA architecture constraints and implementation boundaries (spec only — implementation is a separate planning cycle)

### Out of Scope
- Refactoring `syncSteamGame` internals (already correct)
- Removing `/app/updates/` directory (cosmetic cleanup, deferred)
- Adding new Steam API fields beyond what `syncSteamGame` already fetches
- Offline support for `/manage` or authenticated routes
- Native mobile app packaging (PWA only)

---

## 8. Risk Register

| Risk | Probability | Impact | Mitigation |
|---|---|---|---|
| Stub-then-sync pattern doubles API calls for new games | Certain | Low (2 calls instead of 1, 1.5KB payload each) | Acceptable trade-off for data integrity |
| Race condition: two simultaneous stub creations | Low | Low (one returns 409, can be caught) | UNIQUE constraint on `steamAppId` handles this |
| Service worker caches stale game data | Medium | Medium (user sees old reviews/prices) | Stale-while-revalidate strategy + short TTL for game pages |
| Gamepad API not available on all Steam Deck browser versions | Low | High (feature non-functional) | Feature-detect and silently degrade; SteamOS 3.5+ ships Chromium 114+ with Gamepad API support |

---

## 9. Dependencies

- **Sync unification**: No external dependencies. Pure refactor of existing code.
- **Nav removal**: No dependencies.
- **PWA**: Requires `next-pwa` or `@serwist/next` package, plus `workbox-webpack-plugin` configuration. These are new production dependencies that must be vetted for Next.js 15+ compatibility.