Quick Start Guide#

Installation#

Install dependencies
```
npm install
```
Set up environment
```
cp .env.example .env
```
Start development server
```
npm run dev
```
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#

Lexicons - /lexicons/*.json
- Defines data structure for games, moves, and passes
Database - src/lib/server/db.ts
- SQLite schema using Kysely
Board Component - src/lib/components/Board.svelte
- Wgo.js integration for Go board
API Routes - src/routes/api/games/**
- Game creation, joining, and move recording
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:

Manually set session cookies
Use test DIDs like did:plc:test123
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