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.
1# Database to ATProtocol Migration Index
2
3This document tracks all changes made during the database optimization effort.
4
5## Overview
6
7**Goal**: Minimize database usage while ensuring ATProtocol is the source of truth.
8
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
20
21---
22
23## Changes Made
24
25### 1. ATProtocol Client Enhancements
26**Files**: `src/lib/atproto-client.ts`
27**Commits**: 91f7916, c520d33
28
29**Added Functions**:
30- `fetchGameResigns(gameAtUri)` - Fetch resign records from Constellation backlinks
31- `calculateGameMetadata(gameUri, gameRecord, creatorDid, rkey)` - Calculate action count, last action type, and updated timestamp dynamically by fetching moves/passes/resigns
32- `listPlayerGames(did)` - List all game records from a player's PDS
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
36
37**New Interface**:
38- `GameWithMetadata` - Extends GameRecord with computed fields: `uri`, `rkey`, `creatorDid`, `actionCount`, `lastActionType`, `updatedAt`
39
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
43
44---
45
46### 2. Database Strategy Revision
47**Files**: `src/routes/+page.server.ts`, `src/routes/game/[id]/+page.server.ts`
48**Commit**: c520d33
49
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
54
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
60
61**Status**: ✅ Completed - Database retained for reads
62
63---
64
65## Future Improvements
66
67### Potential Enhancements:
681. **Write-through cache pattern**: Update ATProtocol first, then sync to database
692. **Database rebuild utility**: Script to rebuild database from ATProtocol records
703. **Eventual consistency**: Background job to sync database with ATProtocol periodically
714. **Minimize database writes**: Only update database on game state changes that affect discovery
725. **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
88
89---
90
91## Testing Checklist
92
93After migration, test:
94- [ ] Homepage loads and displays games correctly
95- [ ] Game page works with all game states
96- [ ] Profile page shows player's games
97- [ ] Creating new games works
98- [ ] Joining games works
99- [ ] Making moves works
100- [ ] Passing works
101- [ ] Resigning works
102- [ ] Scoring works
103- [ ] Reactions work
104
105---
106
107## Rollback Instructions
108
109If something breaks:
110
1111. Revert to commit before migration: `git log --oneline` to find the commit
1122. Check this index to see what was changed
1133. Each commit is atomic and can be reverted individually
114
115---
116
117## Notes
118
119- The database was only used as a discovery index, not as source of truth
120- All game data was already in ATProtocol records
121- This migration makes the app more decentralized and resilient