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# Implementation Notes - Go Game with AT Protocol
2
3## Overview
4
5This document provides technical details about the implementation and what needs to be completed for full AT Protocol integration.
6
7## What's Implemented
8
9### 1. Project Structure ✅
10
11The SvelteKit application is fully structured with:
12- Routes for home page, game pages, and API endpoints
13- Server-side rendering and data loading
14- Component organization
15- Database setup with Kysely
16
17### 2. Custom Lexicons ✅
18
19Three custom AT Protocol lexicons are defined in `/lexicons`:
20
21- **boo.sky.go.game**: Game records with players, board size, status
22- **boo.sky.go.move**: Move records with coordinates, captures, and timestamps
23- **boo.sky.go.pass**: Pass action records
24
25These lexicons follow AT Protocol standards and can be used to publish records to the network.
26
27### 3. Database Schema ✅
28
29SQLite database with three main tables:
30- `games`: Local cache of game records
31- `moves`: Local cache of move records
32- `passes`: Local cache of pass records
33
34The database uses AT Protocol URIs as primary keys to maintain consistency with the network.
35
36### 4. Game Logic ✅
37
38The Wgo.js library is integrated for:
39- Board rendering using SVGBoard
40- Move validation using Game class
41- Capture calculation
42- Stone placement and removal
43
44### 5. UI Components ✅
45
46- **Home Page**: Login form, game creation, and game listing
47- **Game Page**: Interactive board, move history, player info
48- **Board Component**: Reusable Wgo.js wrapper with click handling
49
50## What Needs Completion
51
52### 1. OAuth Authentication ⚠️
53
54**Current State:**
55- OAuth routes exist (`/auth/login`, `/auth/callback`, `/auth/logout`)
56- Session management structure is in place
57- OAuth client returns null (placeholder)
58
59**To Complete:**
601. Set up proper NodeOAuthClient configuration:
61 ```typescript
62 import { NodeOAuthClient } from '@atproto/oauth-client-node';
63
64 const client = await NodeOAuthClient.fromClientId({
65 clientId: `${PUBLIC_BASE_URL}/oauth-client-metadata.json`,
66 stateStore: new StateStore(), // Implement state persistence
67 sessionStore: new SessionStore(), // Implement session persistence
68 });
69 ```
70
712. Update `oauth-client-metadata.json` with production URLs
723. Implement proper session encryption (currently using base64 encoding)
734. Handle OAuth flows:
74 - Login initiation with `client.authorize(handle)`
75 - Callback handling with `client.callback(params)`
76 - Session restoration with `client.restore(did)`
77
78### 2. AT Protocol Record Creation ⚠️
79
80**Current State:**
81- Records are created in local database
82- AT URIs are generated correctly
83- Agent creation is commented out
84
85**To Complete:**
861. Create authenticated AtpAgent instances:
87 ```typescript
88 const oauthSession = await client.restore(session.did);
89 const agent = oauthSession.agent;
90 ```
91
922. Create records in AT Protocol:
93 ```typescript
94 await agent.com.atproto.repo.createRecord({
95 repo: session.did,
96 collection: 'boo.sky.go.game',
97 rkey: generatedTid,
98 record: gameRecord,
99 });
100 ```
101
1023. Update records for game state changes (joining, completion)
103
1044. Handle record creation errors and retries
105
106### 3. Firehose Subscription ⚠️
107
108**Current State:**
109- Placeholder functions exist in `src/lib/server/firehose.ts`
110- Database update logic is outlined
111
112**To Complete:**
1131. Install firehose dependencies:
114 ```bash
115 npm install @atproto/sync
116 ```
117
1182. Set up WebSocket connection:
119 ```typescript
120 import { Firehose } from '@atproto/sync';
121
122 const firehose = new Firehose({
123 service: 'wss://bsky.network',
124 filterCollections: [
125 'boo.sky.go.game',
126 'boo.sky.go.move',
127 'boo.sky.go.pass'
128 ]
129 });
130 ```
131
1323. Handle commit events:
133 ```typescript
134 firehose.on('commit', async (evt) => {
135 // Parse CAR blocks
136 // Update local database
137 // Emit real-time updates to clients
138 });
139 ```
140
1414. Implement error handling and reconnection logic
142
143### 4. Real-time Updates ⚠️
144
145**Current State:**
146- Game page reloads after each move
147- No live updates when opponent moves
148
149**To Complete:**
1501. Set up Server-Sent Events or WebSocket connection:
151 ```typescript
152 // In +server.ts
153 export const GET: RequestHandler = async ({ params }) => {
154 const stream = new ReadableStream({
155 start(controller) {
156 // Subscribe to game updates
157 // Send SSE events on changes
158 }
159 });
160
161 return new Response(stream, {
162 headers: {
163 'Content-Type': 'text/event-stream',
164 'Cache-Control': 'no-cache',
165 }
166 });
167 };
168 ```
169
1702. Connect from client:
171 ```typescript
172 const eventSource = new EventSource(`/api/games/${gameId}/stream`);
173 eventSource.onmessage = (event) => {
174 const data = JSON.parse(event.data);
175 // Update board with new move
176 };
177 ```
178
1793. Emit events from firehose when moves are detected
180
181## Development Workflow
182
183### Running the Application
184
1851. Install dependencies:
186 ```bash
187 npm install
188 ```
189
1902. Set up environment variables:
191 ```bash
192 cp .env.example .env
193 # Edit .env with your values
194 ```
195
1963. Start development server:
197 ```bash
198 npm run dev
199 ```
200
2014. Access at http://localhost:5173
202
203### Testing Without OAuth
204
205For development, you can bypass OAuth by:
2061. Manually creating session cookies
2072. Using test DIDs (e.g., `did:plc:test123`)
2083. Testing game logic with local database only
209
210### Type Checking
211
212Run type checking:
213```bash
214npm run check
215```
216
217Note: Some errors related to Node version (<18) may appear but don't affect functionality.
218
219## Production Considerations
220
221### Security
222- Use proper session encryption (not base64)
223- Implement CSRF protection
224- Validate all inputs server-side
225- Use HTTPS for all production traffic
226- Store secrets in environment variables
227
228### Performance
229- Add database indexes for frequently queried fields
230- Implement pagination for game lists
231- Cache game state in memory
232- Use connection pooling for database
233
234### Reliability
235- Add error boundaries in UI
236- Implement retry logic for AT Protocol calls
237- Add logging and monitoring
238- Handle network disconnections gracefully
239
240### Scalability
241- Consider moving to PostgreSQL for larger scale
242- Implement horizontal scaling for API servers
243- Use Redis for session storage
244- Add CDN for static assets
245
246## Testing Strategy
247
248### Unit Tests
249- Move validation logic
250- TID generation
251- Session management
252- Database queries
253
254### Integration Tests
255- OAuth flow end-to-end
256- Game creation and joining
257- Move recording
258- Firehose event handling
259
260### E2E Tests
261- Full game playthrough
262- Multiple players simultaneously
263- Pass and game completion
264- Error scenarios
265
266## Deployment
267
268### Environment Setup
2691. Set production environment variables
2702. Use production OAuth client ID
2713. Configure production database
2724. Set up SSL certificates
273
274### Build Process
275```bash
276npm run build
277```
278
279### Running in Production
280```bash
281node build/index.js
282```
283
284Or use a process manager like PM2:
285```bash
286pm2 start build/index.js --name go-game
287```
288
289## Future Enhancements
290
291### Game Features
292- Automatic territory scoring
293- Time controls (byo-yomi, Fischer)
294- Undo/redo functionality
295- Game analysis tools
296- SGF import/export
297
298### Social Features
299- Game chat using AT Protocol
300- Spectator mode
301- Game reviews and comments
302- Tournament organization
303- Player profiles and stats
304
305### Technical Improvements
306- Progressive Web App (PWA)
307- Offline play capability
308- Mobile app (React Native)
309- Game AI integration
310- Multiple board themes
311
312## Resources
313
314- [AT Protocol Documentation](https://atproto.com/docs)
315- [Wgo.js Documentation](http://wgo.waltheri.net/)
316- [SvelteKit Documentation](https://kit.svelte.dev/)
317- [Kysely Documentation](https://kysely.dev/)
318
319## Support
320
321For questions about:
322- AT Protocol: https://github.com/bluesky-social/atproto
323- Wgo.js: https://github.com/waltheri/wgo.js
324- SvelteKit: https://github.com/sveltejs/kit