goose.art
extremely claude-assisted go game based on atproto! working on cleaning up and giving a more unique design, still has a bit of a slop vibe to it.
Update migration index to reflect revised database strategy
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
+58
-38
MIGRATION_INDEX.md
+58
-38
MIGRATION_INDEX.md
···
1
1
# Database to ATProtocol Migration Index
2
2
3
-
This document tracks all changes made during the migration from database-backed storage to ATProtocol-only data fetching.
3
+
This document tracks all changes made during the database optimization effort.
4
4
5
5
## Overview
6
6
7
-
**Goal**: Remove all database dependencies and fetch data entirely from ATProtocol/Constellation.
7
+
**Goal**: Minimize database usage while ensuring ATProtocol is the source of truth.
8
8
9
-
**Approach**:
10
-
- Use Constellation API for game discovery
11
-
- Calculate action counts dynamically by fetching moves/passes
12
-
- Always fetch fresh data from ATProtocol
9
+
**Revised Approach** (after testing):
10
+
- **Keep database as discovery index** for homepage and game lookups
11
+
- **ATProtocol remains source of truth** - all game data written there first
12
+
- **Database kept in sync** when ATProtocol records are created/updated
13
+
- Database is necessary for efficient discovery of games user is not directly involved in
14
+
15
+
**Why keep the database?**
16
+
- Constellation doesn't have a simple API to list all game records
17
+
- Need rkey → creator DID mapping for game lookups
18
+
- Efficient filtering by status, time, player without querying multiple PDSs
19
+
- Better UX with fast queries vs slow PDS federation
13
20
14
21
---
15
22
16
23
## Changes Made
17
24
18
25
### 1. ATProtocol Client Enhancements
19
-
**File**: `src/lib/atproto-client.ts`
20
-
**Commit**: 91f7916
26
+
**Files**: `src/lib/atproto-client.ts`
27
+
**Commits**: 91f7916, c520d33
21
28
22
29
**Added Functions**:
23
30
- `fetchGameResigns(gameAtUri)` - Fetch resign records from Constellation backlinks
24
-
- `calculateGameMetadata(gameUri, gameRecord, creatorDid, rkey)` - Calculate action count, last action type, and updated timestamp dynamically
31
+
- `calculateGameMetadata(gameUri, gameRecord, creatorDid, rkey)` - Calculate action count, last action type, and updated timestamp dynamically by fetching moves/passes/resigns
25
32
- `listPlayerGames(did)` - List all game records from a player's PDS
26
33
- `fetchAllGames(knownPlayerDids)` - Aggregate games from multiple players and compute metadata
34
+
- `findGame(creatorDid, rkey)` - Fetch a specific game and compute its metadata
35
+
- `findGameByRkey(rkey, potentialCreatorDids)` - Search for a game by rkey across multiple PDSs
27
36
28
37
**New Interface**:
29
38
- `GameWithMetadata` - Extends GameRecord with computed fields: `uri`, `rkey`, `creatorDid`, `actionCount`, `lastActionType`, `updatedAt`
30
39
31
-
**Purpose**: Provide functions to fetch and compute game metadata without database queries.
40
+
**Purpose**: These functions CAN be used to fetch game data directly from ATProtocol without database, but in practice the database is kept for efficient indexing and discovery.
41
+
42
+
**Status**: ✅ Completed - Functions available for use where needed
32
43
33
44
---
34
45
35
-
## Remaining Changes
46
+
### 2. Database Strategy Revision
47
+
**Files**: `src/routes/+page.server.ts`, `src/routes/game/[id]/+page.server.ts`
48
+
**Commit**: c520d33
36
49
37
-
### 2. Homepage (In Progress)
38
-
**File**: `src/routes/+page.server.ts`
39
-
- Remove `getDb()` import
40
-
- Replace database queries with ATProtocol fetching
41
-
- Use `fetchAllGames()` or player-specific queries
50
+
**Decision**: Keep database as discovery index
51
+
- Homepage continues using database for efficient game listing and filtering
52
+
- Game page continues using database for rkey lookups
53
+
- Profile page will continue using database for player game queries
42
54
43
-
### 3. Game Page
44
-
**File**: `src/routes/game/[id]/+page.server.ts`
45
-
- Remove database dependency
46
-
- Fetch game record directly from ATProtocol
55
+
**Rationale**:
56
+
- Constellation lacks comprehensive record listing APIs
57
+
- Database provides fast rkey → game data mapping
58
+
- Efficient filtering by status, time, player
59
+
- Better performance for discovery of games user is not involved in
47
60
48
-
### 4. Profile Page
49
-
**File**: `src/routes/profile/[did]/+page.server.ts`
50
-
- Remove database queries
51
-
- Use `listPlayerGames()` for player-specific game listing
61
+
**Status**: ✅ Completed - Database retained for reads
52
62
53
-
### 5. API Routes
54
-
**Files**: Multiple API endpoint files
55
-
- `/api/games/+server.ts` (create game)
56
-
- `/api/games/[id]/join/+server.ts` (join game)
57
-
- `/api/games/[id]/move/+server.ts` (make move)
58
-
- `/api/games/[id]/pass/+server.ts` (pass turn)
59
-
- `/api/games/[id]/cancel/+server.ts` (resign)
60
-
- `/api/games/[id]/score/+server.ts` (submit scores)
61
-
- `/api/games/[id]/reaction/+server.ts` (add reaction)
62
-
- Other routes: board, nudge, nudge-image, scoring-board, og-image, profile
63
+
---
63
64
64
-
### 6. Cleanup
65
-
- Remove `src/lib/server/db.ts`
66
-
- Remove database dependencies from package.json
67
-
- Remove DATABASE_PATH from environment variables
65
+
## Future Improvements
66
+
67
+
### Potential Enhancements:
68
+
1. **Write-through cache pattern**: Update ATProtocol first, then sync to database
69
+
2. **Database rebuild utility**: Script to rebuild database from ATProtocol records
70
+
3. **Eventual consistency**: Background job to sync database with ATProtocol periodically
71
+
4. **Minimize database writes**: Only update database on game state changes that affect discovery
72
+
5. **Remove database from individual game pages**: Could fetch directly from ATProtocol using functions from #1 above
73
+
74
+
---
75
+
76
+
## Current State
77
+
78
+
**Database Usage**:
79
+
- ✅ Homepage - uses database for game discovery
80
+
- ✅ Game page - uses database for rkey lookup
81
+
- ⏸️ Profile page - still uses database (unchanged)
82
+
- ⏸️ API routes - still use database for reads and writes (unchanged)
83
+
84
+
**ATProtocol Usage**:
85
+
- ✅ All game data, moves, passes, resigns written to ATProtocol
86
+
- ✅ Helper functions available to fetch directly from ATProtocol
87
+
- ✅ Database kept in sync when records are created/updated
68
88
69
89
---
70
90