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# Project Summary - Go Game with AT Protocol
2
3## Overview
4
5This project implements a web-based Go game application using SvelteKit, integrated with AT Protocol for decentralized game state storage. The application demonstrates how to use custom AT Protocol lexicons to store game data on the decentralized social network.
6
7## Complete File Structure
8
9```
10atprotogo/
11├── src/
12│ ├── app.css # Global styles
13│ ├── app.html # HTML template
14│ ├── hooks.server.ts # Server hooks (firehose init)
15│ │
16│ ├── lib/
17│ │ ├── env.ts # Environment configuration
18│ │ ├── components/
19│ │ │ └── Board.svelte # Wgo.js board component
20│ │ └── server/
21│ │ ├── auth.ts # OAuth client & session management
22│ │ ├── db.ts # Kysely database setup
23│ │ └── firehose.ts # AT Protocol firehose subscription
24│ │
25│ └── routes/
26│ ├── +layout.svelte # App layout wrapper
27│ ├── +page.svelte # Home page (game list)
28│ ├── +page.server.ts # Home page data loading
29│ │
30│ ├── auth/
31│ │ ├── callback/+server.ts # OAuth callback handler
32│ │ ├── login/+server.ts # OAuth login initiation
33│ │ └── logout/+server.ts # Logout handler
34│ │
35│ ├── game/[id]/
36│ │ ├── +page.svelte # Game board UI
37│ │ └── +page.server.ts # Game data loading
38│ │
39│ └── api/
40│ └── games/
41│ ├── +server.ts # Create game API
42│ └── [id]/
43│ ├── join/+server.ts # Join game API
44│ ├── move/+server.ts # Record move API
45│ └── pass/+server.ts # Record pass API
46│
47├── lexicons/
48│ ├── boo.sky.go.game.json # Game record lexicon
49│ ├── boo.sky.go.move.json # Move record lexicon
50│ └── boo.sky.go.pass.json # Pass record lexicon
51│
52├── static/
53│ └── oauth-client-metadata.json # OAuth client metadata
54│
55├── data/ # SQLite database directory
56│ └── app.db # (created at runtime)
57│
58├── .env # Environment variables
59├── .env.example # Environment template
60├── .gitignore # Git ignore rules
61├── package.json # NPM dependencies
62├── svelte.config.js # SvelteKit configuration
63├── tsconfig.json # TypeScript configuration
64├── vite.config.ts # Vite configuration
65├── README.md # Project documentation
66├── IMPLEMENTATION_NOTES.md # Technical implementation guide
67└── PROJECT_SUMMARY.md # This file
68```
69
70## Key Components
71
72### 1. Custom AT Protocol Lexicons
73
74Three lexicon definitions specify the data structure for Go games:
75
76**boo.sky.go.game**
77- playerOne (DID)
78- playerTwo (DID, optional)
79- boardSize (9, 13, or 19)
80- status (waiting, active, completed)
81- winner (DID, optional)
82- createdAt (datetime)
83
84**boo.sky.go.move**
85- game (AT URI reference)
86- player (DID)
87- moveNumber (integer)
88- x, y (coordinates)
89- color (black or white)
90- captureCount (integer)
91- createdAt (datetime)
92
93**boo.sky.go.pass**
94- game (AT URI reference)
95- player (DID)
96- moveNumber (integer)
97- color (black or white)
98- createdAt (datetime)
99
100### 2. Database Schema
101
102SQLite tables mirror the lexicon structure:
103
104**games**
105- id (AT URI, primary key)
106- rkey (TID)
107- player_one, player_two
108- board_size
109- status
110- winner
111- created_at, updated_at
112
113**moves**
114- id (AT URI, primary key)
115- rkey (TID)
116- game_id (foreign key)
117- player, move_number
118- x, y, color
119- capture_count
120- created_at
121
122**passes**
123- id (AT URI, primary key)
124- rkey (TID)
125- game_id (foreign key)
126- player, move_number
127- color
128- created_at
129
130### 3. Game Flow
131
1321. **User Authentication** (placeholder)
133 - User enters Bluesky handle
134 - OAuth flow redirects to AT Protocol
135 - Session stored with DID
136
1372. **Create Game**
138 - Select board size (9x9, 13x13, 19x19)
139 - Generate TID for game record
140 - Create game record (local DB only in current implementation)
141 - Status: "waiting"
142
1433. **Join Game**
144 - Browse available games
145 - Click "Join" on waiting game
146 - Update game record with playerTwo
147 - Status: "active"
148
1494. **Play Game**
150 - Players alternate placing stones
151 - Wgo.js validates moves
152 - Calculate captures
153 - Create move records
154 - Update UI in real-time
155
1565. **Pass**
157 - Player clicks Pass button
158 - Create pass record
159 - Check for two consecutive passes
160 - If yes: game status → "completed"
161
1626. **Game End**
163 - Two consecutive passes
164 - Update game status
165 - Display winner (manual or calculated)
166
167### 4. UI Components
168
169**Home Page** (`src/routes/+page.svelte`)
170- Login form (OAuth)
171- Create game section with board size selector
172- List of available games (waiting/active)
173- Join button for waiting games
174
175**Game Page** (`src/routes/game/[id]/+page.svelte`)
176- Wgo.js board component
177- Current turn indicator
178- Pass button
179- Game info (players, status, board size)
180- Move history list
181
182**Board Component** (`src/lib/components/Board.svelte`)
183- SVGBoard from Wgo.js
184- Click handling for stone placement
185- Move validation with Game class
186- Capture calculation and stone removal
187- Interactive/readonly modes
188
189### 5. API Endpoints
190
191**POST /auth/login**
192- Initiates OAuth flow with handle
193- Returns authorization URL
194
195**GET /auth/callback**
196- Handles OAuth callback
197- Stores session
198- Redirects to home page
199
200**POST /auth/logout**
201- Clears session cookie
202- Redirects to home page
203
204**POST /api/games**
205- Creates new game record
206- Params: boardSize
207- Returns: gameId, uri
208
209**POST /api/games/[id]/join**
210- Joins waiting game as playerTwo
211- Updates game status to "active"
212
213**POST /api/games/[id]/move**
214- Records stone placement
215- Params: x, y, captureCount
216- Validates turn order
217- Creates move record
218
219**POST /api/games/[id]/pass**
220- Records pass action
221- Checks for game end (two consecutive passes)
222- Updates game status if completed
223
224## Technical Stack
225
226### Frontend
227- **Framework**: SvelteKit 5
228- **Language**: TypeScript
229- **Go Board**: Wgo.js 3.0.0-alpha.10
230- **Styling**: Custom CSS with component styles
231
232### Backend
233- **Runtime**: Node.js (18+ recommended)
234- **Framework**: SvelteKit server-side
235- **Database**: SQLite with better-sqlite3
236- **Query Builder**: Kysely 0.27.0
237
238### AT Protocol
239- **OAuth**: @atproto/oauth-client-node 0.1.0
240- **API**: @atproto/api 0.13.0
241- **Lexicon**: @atproto/lexicon 0.4.0
242
243## Implementation Status
244
245### ✅ Fully Implemented
246- Project structure and configuration
247- Custom lexicon definitions
248- Database schema and migrations
249- Wgo.js board integration
250- Game creation UI and API
251- Game joining UI and API
252- Move recording UI and API
253- Pass functionality
254- Move history display
255- Game state management
256- TID generation for records
257- AT URI structure
258
259### ⚠️ Partially Implemented
260- OAuth authentication (structure exists, needs full setup)
261- AT Protocol record creation (URIs generated, not written to network)
262- Session management (simple encoding, needs encryption)
263
264### 📋 Placeholder/TODO
265- Firehose subscription (structure exists, needs WebSocket implementation)
266- Real-time updates (page refresh currently used)
267- Automatic scoring (game ends on double pass, no winner calculation)
268
269## How to Complete the Implementation
270
271### Step 1: OAuth Setup
272
2731. Properly configure NodeOAuthClient:
274```typescript
275const client = await NodeOAuthClient.fromClientId({
276 clientId: `${PUBLIC_BASE_URL}/oauth-client-metadata.json`,
277 stateStore: new StateStore(),
278 sessionStore: new SessionStore(),
279});
280```
281
2822. Update OAuth routes to use the client
2833. Test OAuth flow with real Bluesky accounts
284
285### Step 2: AT Protocol Records
286
2871. Create authenticated agents:
288```typescript
289const oauthSession = await client.restore(session.did);
290const agent = oauthSession.agent;
291```
292
2932. Create records on the network:
294```typescript
295await agent.com.atproto.repo.createRecord({
296 repo: session.did,
297 collection: 'boo.sky.go.game',
298 rkey: tid,
299 record: gameData,
300});
301```
302
3033. Test record creation and retrieval
304
305### Step 3: Firehose Integration
306
3071. Set up WebSocket connection to AT Protocol relay
3082. Subscribe to custom lexicon collections
3093. Parse commit events and update database
3104. Emit real-time updates to connected clients
311
312### Step 4: Real-time Updates
313
3141. Implement Server-Sent Events or WebSockets
3152. Subscribe clients to game updates
3163. Push moves from firehose to clients
3174. Update board without page refresh
318
319## Running the Project
320
321### Development
322
323```bash
324# Install dependencies
325npm install
326
327# Set up environment
328cp .env.example .env
329# Edit .env with your configuration
330
331# Start development server
332npm run dev
333```
334
335Access at http://localhost:5173
336
337### Type Checking
338
339```bash
340npm run check
341```
342
343Note: Some warnings about Node version may appear (need 18+)
344
345### Building for Production
346
347```bash
348npm run build
349npm run preview
350```
351
352## Environment Variables
353
354```env
355DATABASE_PATH=./data/app.db
356SESSION_SECRET=your-random-secret-here
357```
358
359## Dependencies
360
361### Production
362- @atproto/api: ^0.13.0
363- @atproto/oauth-client-node: ^0.1.0
364- @atproto/lexicon: ^0.4.0
365- @atproto/xrpc-server: ^0.6.0
366- kysely: ^0.27.0
367- better-sqlite3: ^11.0.0
368- wgo: ^3.0.0-alpha.10
369
370### Development
371- @sveltejs/kit: ^2.0.0
372- @sveltejs/vite-plugin-svelte: ^4.0.0
373- svelte: ^5.0.0
374- typescript: ^5.0.0
375- vite: ^5.0.0
376
377## License
378
379MIT
380
381## Resources
382
383- [AT Protocol Documentation](https://atproto.com/)
384- [Wgo.js Documentation](http://wgo.waltheri.net/)
385- [SvelteKit Documentation](https://kit.svelte.dev/)
386- [Bluesky](https://bsky.app/)