Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
298 lines (211 loc) · 5.98 KB

GETTING_STARTED.md

File metadata and controls

298 lines (211 loc) · 5.98 KB

Getting Started with Klura

Welcome to Klura! This guide will help you get up and running with the development environment.

Prerequisites

  • Node.js: >= 18.0.0
  • pnpm: >= 8.0.0 (Install with npm install -g pnpm)
  • Git: Latest version

Installation

All dependencies have been installed. If you need to reinstall:

pnpm install

Project Structure

Klura/
├── apps/
│   ├── backend/              # NestJS backend (initialized)
│   └── klura-front-end/      # Vue 3 frontend (initialized)
├── packages/
│   └── shared/               # Shared types & schemas (✅ complete)
└── game-content/             # Game definitions (✅ example content)

Development Commands

Start Everything (Parallel)

pnpm dev

This starts both frontend and backend simultaneously.

Frontend Only

pnpm dev:frontend
# or
cd apps/klura-front-end && pnpm dev

Frontend will be available at: http://localhost:5173

Backend Only

pnpm dev:backend
# or
cd apps/backend && pnpm dev

Backend will be available at: http://localhost:3000

Shared Package

The shared package has been built and is ready to use. To rebuild:

pnpm build:shared
# or
cd packages/shared && pnpm build

Verification

Check Backend Health

curl http://localhost:3000/health

Expected response:

{
  "status": "ok",
  "timestamp": "2025-12-26T..."
}

Type Checking

# Check all packages
pnpm type-check

# Check specific package
pnpm --filter @klura/backend type-check

What's Been Set Up

✅ Completed

  1. Monorepo Configuration

    • pnpm workspaces configured
    • Root package.json with monorepo scripts

  2. Shared Package (@klura/shared)

    • ✅ Zod schemas for all game entities
    • ✅ TypeScript types (inferred from schemas)
    • ✅ Theme system (base + victorian-gothic)
    • ✅ Built and ready for import

  3. Backend (@klura/backend)

    • ✅ NestJS initialized with Fastify
    • ✅ TypeScript strict mode enabled
    • ✅ Basic app structure (AppModule, AppController, AppService)
    • ✅ Health check endpoint
    • ✅ ESLint configured
    • ✅ Dependencies installed

  4. Frontend (klura-front-end)

    • ✅ Vue 3 + Vite scaffolded
    • ✅ TypeScript configured
    • ✅ Ready for development

  5. Game Content Examples

    • ✅ Murder Mystery Engine template
    • ✅ Blackwood Mansion variant
    • ✅ Blackwood narrative story
    • Demonstrates the Game-as-Data pattern

Using the Shared Package

The shared package is already linked via pnpm workspaces. Import it in backend:

// In backend code
import { GameState, GameVariantSchema } from '@klura/shared';
import { victorianGothicTheme } from '@klura/shared/themes';

// Validate data
const validatedVariant = GameVariantSchema.parse(inputData);

// Use types
const state: GameState = {
  roomId: 'uuid',
  status: 'LOBBY',
  // ...
};

Next Steps

Phase 1: Backend Core Engine

  1. Create Core Modules

    • src/core/game-engine/ - Main game orchestration
    • src/core/persona-engine/ - Role assignment
    • src/core/content-loader/ - Load game configs

  2. Set Up Infrastructure

    • Redis connection service
    • tRPC router module
    • WebSocket gateway

  3. Create First Plugin

    • src/plugins/murder-mystery.plugin.ts
    • Implement ACCUSE_PLAYER, EXAMINE_CLUE actions

Phase 2: Frontend Development

  1. Set Up State Management

    • Install and configure Pinia
    • Create game state store

  2. Create UI Components

    • Lobby screen
    • Game board
    • Persona-specific views

  3. Integrate Real-time

    • Install socket.io-client
    • Connect to backend WebSocket
    • Handle GAME_UPDATE events

Environment Setup

Backend Environment

Copy .env.example to .env in apps/backend/:

cd apps/backend
cp .env.example .env

Edit .env with your configuration:

  • Redis connection details
  • Supabase credentials
  • JWT secret

Development Workflow

Following TDD principles:

  1. Write a failing test (Red)
  2. Implement minimal code to pass (Green)
  3. Refactor for quality (Refactor)
  4. Commit after each completed task

Running Tests

# Shared package
cd packages/shared && pnpm test

# Backend
cd apps/backend && pnpm test

# All packages
pnpm test

Architecture Principles

Command & Sync Pattern

Critical: Mutations go through tRPC, updates via Socket.IO.

Client → tRPC (validate) → Backend (process) → Redis (save)
                                                    ↓
Client ← Socket.IO (broadcast) ← GameGateway ← ─────┘

Game-as-Data Pattern

New games are added via JSON configuration, not code:

/game-content/
  ├── templates/          # Reusable mechanics
  ├── variants/          # Themed instances
  └── stories/           # Narrative content

Troubleshooting

Port Already in Use

If port 3000 or 5173 is already in use:

# Change backend port
# Edit apps/backend/.env: PORT=3001

# Change frontend port
# Edit apps/klura-front-end/vite.config.ts: server.port

Type Errors

If you see type errors after changes to shared package:

# Rebuild shared package
pnpm --filter @klura/shared build

# Restart TypeScript server in your IDE

pnpm Workspace Issues

If packages aren't linking correctly:

# Clean and reinstall
pnpm clean
pnpm install

Resources

  • Architecture: /conductor/code_styleguides/architecture.md
  • Tech Stack: /conductor/tech-stack.md
  • CLAUDE.md: Guidance for Claude Code
  • Project Structure: /PROJECT_STRUCTURE.md

Support

If you encounter issues:

  1. Check the documentation in /conductor/
  2. Verify all prerequisites are installed
  3. Ensure environment variables are set correctly
  4. Check that all dependencies installed successfully

Ready to Start? Run pnpm dev and start building!