Quick Start Guide #

Installation #

1. Install dependencies

   npm install
   

2. Set up environment

   cp .env.example .env
   

3. Start development server

   npm run dev
   

4. Open your browser

   • Navigate to http://localhost:5173

Project Status #

This is a demonstration project showing how to architect a Go game with AT Protocol integration.

What Works #

• ✅ Project structure and configuration
• ✅ Custom AT Protocol lexicons defined
• ✅ SQLite database with Kysely
• ✅ Wgo.js board component
• ✅ Game creation and listing UI
• ✅ Move recording logic
• ✅ Pass functionality

What's Simplified/Placeholder #

• ⚠️ OAuth authentication (needs full setup)
• ⚠️ AT Protocol record creation (generates URIs but doesn't write to network)
• ⚠️ Firehose subscription (structure in place)
• ⚠️ Real-time updates (uses page refresh)

Key Files to Review #

1. Lexicons - /lexicons/*.json

   • Defines data structure for games, moves, and passes

2. Database - src/lib/server/db.ts

   • SQLite schema using Kysely

3. Board Component - src/lib/components/Board.svelte

   • Wgo.js integration for Go board

4. API Routes - src/routes/api/games/**

   • Game creation, joining, and move recording

5. Implementation Guide - IMPLEMENTATION_NOTES.md

   • Detailed technical documentation

Next Steps to Complete #

1. Set up OAuth (30-60 min) #

• Configure NodeOAuthClient in src/lib/server/auth.ts
• Test with real Bluesky accounts

2. Enable AT Protocol Records (30-60 min) #

• Uncomment agent creation code
• Test creating records on the network

3. Add Firehose (2-4 hours) #

• Install @atproto/sync
• Set up WebSocket connection
• Parse commit events

4. Real-time Updates (1-2 hours) #

• Implement Server-Sent Events
• Connect firehose to UI updates

Development Tips #

Running Type Check #

npm run check

Viewing Database #

sqlite3 data/app.db
.tables
.schema games
SELECT * FROM games;

Testing Without OAuth #

For local development, you can bypass OAuth:

1. Manually set session cookies
2. Use test DIDs like did:plc:test123
3. Test game logic with local DB only

Common Issues #

Node Version Warnings #

The project requires Node 18+. If you see warnings about Node version (current: v17.9.0), consider upgrading for best results.

TypeScript Errors #

Some 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.

Database Not Found #

The database is created automatically on first run in the data/ directory. Make sure the directory exists and is writable.

Learning Resources #

• AT Protocol: https://atproto.com/docs
• Wgo.js: http://wgo.waltheri.net/
• SvelteKit: https://kit.svelte.dev/docs
• Kysely: https://kysely.dev/

Questions? #

Check these documents:

• README.md - Project overview and features
• IMPLEMENTATION_NOTES.md - Detailed technical guide
• PROJECT_SUMMARY.md - Complete file structure and architecture