Klura - Multiplayer Board Game Platform

A real-time, multiplayer digital board game platform with asymmetric gameplay and modular game architecture.

Overview

Klura brings friends together for interactive, narrative-driven social experiences. Players join via QR code or link and receive role-specific interfaces based on their assigned persona (e.g., Detective vs Murderer in a Murder Mystery game).

Key Features

• Real-time Multiplayer - Seamless state synchronization via WebSockets
• Asymmetric Gameplay - Different players see different information based on their role
• Game-as-Data - Scale to 100s of games via JSON configuration
• Modular Architecture - Add new games without code changes
• Theme System - Each game has its own visual identity

Quick Start

# Install dependencies
pnpm install

# Start development servers (frontend + backend)
pnpm dev

# Frontend: http://localhost:5173
# Backend: http://localhost:3000

For detailed setup instructions, see GETTING_STARTED.md.

Project Status

Phase: Greenfield - Foundation Complete ✅

What's Ready

• ✅ Monorepo structure configured
• ✅ Shared package with types & schemas
• ✅ Backend initialized (NestJS + Fastify)
• ✅ Frontend initialized (Vue 3 + Vite)
• ✅ Example game content (Murder Mystery)
• ✅ Development servers running

Next Steps

• Implement core game engine
• Create tRPC API layer
• Set up WebSocket gateway
• Build first plugin (Murder Mystery)
• Create UI components

See GETTING_STARTED.md for the full roadmap.

Technology Stack

Frontend

• Framework: Vue 3 (Composition API)
• Build Tool: Vite
• Styling: Tailwind CSS
• State: Pinia
• Real-time: socket.io-client

Backend

• Framework: NestJS (Fastify adapter)
• API: tRPC (type-safe)
• Real-time: Socket.IO
• Database: Redis (hot) + PostgreSQL (cold)

Shared

• Validation: Zod
• Language: TypeScript (strict mode)
• Monorepo: pnpm workspaces

Architecture

Command & Sync Pattern

Client Action → tRPC (validates) → Backend (processes) → Redis (saves)
                                                              ↓
Client UI ← Socket.IO (broadcasts) ← GameGateway ← ──────────┘

Golden Rule: Mutations go through tRPC. Updates come through Socket.IO.

Game-as-Data Pattern

Games are defined through configuration, not code:

Game Template (Mechanics) → Game Variant (Instance) → Story (Narrative)

Example: Murder Mystery Engine → Blackwood Mansion → Blackwood Narrative

Project Structure

Klura/
├── apps/
│   ├── backend/              # NestJS backend
│   │   ├── src/
│   │   │   ├── core/         # Game-agnostic engine
│   │   │   ├── plugins/      # Game-specific mechanics
│   │   │   ├── admin/        # Content management
│   │   │   └── modules/      # tRPC, auth, websocket
│   │   └── package.json
│   │
│   └── klura-front-end/      # Vue 3 frontend
│       ├── src/
│       └── package.json
│
├── packages/
│   └── shared/               # Shared contracts
│       ├── schemas/          # Zod validation
│       ├── types/            # TypeScript types
│       └── themes/           # Visual styling
│
├── game-content/             # Game definitions (JSON)
│   ├── templates/            # Reusable mechanics
│   ├── variants/             # Themed instances
│   └── stories/              # Narrative content
│
└── conductor/                # Documentation
    ├── tech-stack.md
    ├── product.md
    └── code_styleguides/

Documentation

• GETTING_STARTED.md - Setup and development guide
• CLAUDE.md - AI assistant guidance
• PROJECT_STRUCTURE.md - Detailed architecture
• conductor/code_styleguides/architecture.md - Scalability architecture

Development

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 8.0.0

Commands

# Development
pnpm dev              # Start all services
pnpm dev:frontend     # Frontend only
pnpm dev:backend      # Backend only

# Building
pnpm build            # Build all packages
pnpm build:shared     # Build shared package

# Testing
pnpm test             # Run all tests
pnpm type-check       # Type check all packages

# Linting
pnpm lint             # Lint all packages

Workflow

Following Test-Driven Development (TDD):

1. Write failing test (Red)
2. Implement minimal code (Green)
3. Refactor (Refactor)
4. Commit atomically

Maintain 80% test coverage for all new code.

Contributing

Code Style

• TypeScript: Strict mode, explicit return types
• Naming: PascalCase (types), camelCase (variables), UPPER_SNAKE_CASE (constants)
• Functions: Early returns, async/await over promises
• Vue: <script setup>, no business logic in components

See /conductor/code_styleguides/ for detailed guidelines.

Architectural Constraints

1. No game logic on client - Server is authoritative
2. tRPC for mutations - Socket.IO only for updates
3. No any type in shared package
4. Mobile-first UI - Players join via QR codes

License

[To be determined]

Support

For questions or issues:

• Check documentation in /conductor/
• Review architecture in PROJECT_STRUCTURE.md
• See troubleshooting in GETTING_STARTED.md

---

Built with ❤️ for bringing friends together through play