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# Quick Start Guide
2
3## Installation
4
51. **Install dependencies**
6 ```bash
7 npm install
8 ```
9
102. **Set up environment**
11 ```bash
12 cp .env.example .env
13 ```
14
153. **Start development server**
16 ```bash
17 npm run dev
18 ```
19
204. **Open your browser**
21 - Navigate to http://localhost:5173
22
23## Project Status
24
25This is a **demonstration project** showing how to architect a Go game with AT Protocol integration.
26
27### What Works
28- ✅ Project structure and configuration
29- ✅ Custom AT Protocol lexicons defined
30- ✅ SQLite database with Kysely
31- ✅ Wgo.js board component
32- ✅ Game creation and listing UI
33- ✅ Move recording logic
34- ✅ Pass functionality
35
36### What's Simplified/Placeholder
37- ⚠️ OAuth authentication (needs full setup)
38- ⚠️ AT Protocol record creation (generates URIs but doesn't write to network)
39- ⚠️ Firehose subscription (structure in place)
40- ⚠️ Real-time updates (uses page refresh)
41
42## Key Files to Review
43
441. **Lexicons** - `/lexicons/*.json`
45 - Defines data structure for games, moves, and passes
46
472. **Database** - `src/lib/server/db.ts`
48 - SQLite schema using Kysely
49
503. **Board Component** - `src/lib/components/Board.svelte`
51 - Wgo.js integration for Go board
52
534. **API Routes** - `src/routes/api/games/**`
54 - Game creation, joining, and move recording
55
565. **Implementation Guide** - `IMPLEMENTATION_NOTES.md`
57 - Detailed technical documentation
58
59## Next Steps to Complete
60
61### 1. Set up OAuth (30-60 min)
62- Configure NodeOAuthClient in `src/lib/server/auth.ts`
63- Test with real Bluesky accounts
64
65### 2. Enable AT Protocol Records (30-60 min)
66- Uncomment agent creation code
67- Test creating records on the network
68
69### 3. Add Firehose (2-4 hours)
70- Install @atproto/sync
71- Set up WebSocket connection
72- Parse commit events
73
74### 4. Real-time Updates (1-2 hours)
75- Implement Server-Sent Events
76- Connect firehose to UI updates
77
78## Development Tips
79
80### Running Type Check
81```bash
82npm run check
83```
84
85### Viewing Database
86```bash
87sqlite3 data/app.db
88.tables
89.schema games
90SELECT * FROM games;
91```
92
93### Testing Without OAuth
94For local development, you can bypass OAuth:
951. Manually set session cookies
962. Use test DIDs like `did:plc:test123`
973. Test game logic with local DB only
98
99## Common Issues
100
101### Node Version Warnings
102The project requires Node 18+. If you see warnings about Node version (current: v17.9.0), consider upgrading for best results.
103
104### TypeScript Errors
105Some TypeScript errors related to AT Protocol OAuth may appear. These are expected in the demo state and will be resolved when OAuth is fully implemented.
106
107### Database Not Found
108The database is created automatically on first run in the `data/` directory. Make sure the directory exists and is writable.
109
110## Learning Resources
111
112- **AT Protocol**: https://atproto.com/docs
113- **Wgo.js**: http://wgo.waltheri.net/
114- **SvelteKit**: https://kit.svelte.dev/docs
115- **Kysely**: https://kysely.dev/
116
117## Questions?
118
119Check these documents:
120- `README.md` - Project overview and features
121- `IMPLEMENTATION_NOTES.md` - Detailed technical guide
122- `PROJECT_SUMMARY.md` - Complete file structure and architecture