Boardly

Boardly is a real-time multiplayer board games platform built with Next.js, TypeScript, Prisma, PostgreSQL, and a standalone Socket.IO server.

Production: https://boardly.online

What this repository contains

• Next.js app (HTTP API, auth, pages)
• Socket.IO server (socket-server.ts) for real-time lobby/game events
• Shared game engine abstractions (lib/game-engine.ts)
• Game implementations:
  • Stable registered games: Yahtzee, Guess the Spy, Tic-Tac-Toe, Rock Paper Scissors, Memory
  • Feature-flagged/experimental games: Telephone Doodle, Sketch and Guess, Liars Party, Fake Artist, Alias

Architecture at a glance

• App server: :3000 (Next.js)
• Socket server: :3001 (Socket.IO)
• Database: PostgreSQL (Supabase + Prisma)

Flow: Client action -> API route -> DB update -> notify socket server -> room broadcast -> client reconcile

Quick start

1) Install

npm install

2) Configure environment

cp .env.example .env.local

Fill required values in .env.local.

Important:

• Use NEXTAUTH_SECRET as the single signing secret for auth/session tokens.
• Guest authentication uses signed guest JWTs (X-Guest-Token).

3) Prepare database

npm run db:generate
npm run db:push

4) Start development

npm run dev:all

Or run separately:

npm run dev
npm run socket:dev

Common scripts

npm run dev            # Next.js
npm run socket:dev     # Socket.IO server
npm run dev:all        # both
npm run build          # prisma generate + next build
npm run test
npm run lint
npm run check:locales
npm run db:generate
npm run db:push
npm run db:migrate
npm run db:audit
npm run db:rls:smoke

Documentation map

• Project docs index: docs/README.md
• Full local-only setup: docs/LOCAL_SETUP.md
• Product direction: docs/PROJECT_VISION.md
• System design and data flows: docs/ARCHITECTURE.md
• Local/prod operations and deployment: docs/OPERATIONS.md
• Current roadmap: docs/ROADMAP.md
• Contribution workflow: docs/CONTRIBUTING.md
• Security model details: docs/SECURITY_MODEL.md
• Realtime telemetry baseline: docs/REALTIME_TELEMETRY.md
• Dependency maintenance plan: docs/DEPENDENCY_UPGRADE_PLAN.md
• Obsidian vault workflow: docs/OBSIDIAN_VAULT.md
• Bot developer guide: lib/bots/README.md
• Migrations and RLS notes: prisma/migrations/README.md
• AI agent instructions: .github/copilot-instructions.md

Community and policy

• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md
• License: LICENSE