From 658ebe08fe65ca8fe52bdca86fbad835bf4913fe Mon Sep 17 00:00:00 2001
From: Till-JS <101404291+Till-JS@users.noreply.github.com>
Date: Thu, 27 Nov 2025 15:46:57 +0100
Subject: [PATCH] docs(voxel-lava): add project documentation and env config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add CLAUDE.md with project overview, API endpoints, and setup guide
- Add voxel-lava environment variables to .env.development

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .env.development           |   8 +++
 games/voxel-lava/CLAUDE.md | 144 +++++++++++++++++++++++++++++++++++++
 2 files changed, 152 insertions(+)
 create mode 100644 games/voxel-lava/CLAUDE.md

diff --git a/.env.development b/.env.development
index ded684506..56f658970 100644
--- a/.env.development
+++ b/.env.development
@@ -134,3 +134,11 @@ QUOTE_DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/quote
 
 PRESI_BACKEND_PORT=3008
 PRESI_DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/presi
+
+# ============================================
+# VOXEL-LAVA PROJECT
+# ============================================
+
+VOXEL_LAVA_BACKEND_PORT=3010
+VOXEL_LAVA_DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/voxel_lava
+VOXEL_LAVA_API_URL=http://localhost:3010
diff --git a/games/voxel-lava/CLAUDE.md b/games/voxel-lava/CLAUDE.md
new file mode 100644
index 000000000..cf4d23ced
--- /dev/null
+++ b/games/voxel-lava/CLAUDE.md
@@ -0,0 +1,144 @@
+# Voxel-Lava Project Guide
+
+## Project Overview
+
+Voxel-Lava is a 3D voxel building and platforming game built with SvelteKit and Three.js. Players can create levels, share them publicly, and play levels created by others.
+
+## Project Structure
+
+```
+games/voxel-lava/
+├── apps/
+│   ├── web/           # SvelteKit web application (@voxel-lava/web)
+│   └── backend/       # NestJS API server (@voxel-lava/backend)
+├── packages/          # Shared code (optional)
+├── package.json       # Workspace root
+├── pnpm-workspace.yaml
+├── turbo.json
+└── CLAUDE.md
+```
+
+## Commands
+
+### Root Level (from monorepo root)
+```bash
+pnpm voxel-lava:dev              # Run web + backend
+pnpm dev:voxel-lava:web          # Start web app only
+pnpm dev:voxel-lava:backend      # Start backend only
+pnpm voxel-lava:db:push          # Push DB schema
+pnpm voxel-lava:db:studio        # Open Drizzle Studio
+```
+
+### Backend (games/voxel-lava/apps/backend)
+```bash
+pnpm start:dev                   # Start with hot reload
+pnpm build                       # Build for production
+pnpm migration:generate          # Generate DB migration
+pnpm migration:run               # Run migrations
+pnpm db:push                     # Push schema directly
+pnpm db:studio                   # Open Drizzle Studio
+```
+
+### Web App (games/voxel-lava/apps/web)
+```bash
+pnpm dev                         # Start dev server (port 5180)
+pnpm build                       # Build for production
+pnpm preview                     # Preview production build
+pnpm check                       # Type check
+```
+
+## Technology Stack
+
+- **Web**: SvelteKit 2.x, Svelte 5, Three.js, Tailwind CSS
+- **Backend**: NestJS 10, Drizzle ORM, PostgreSQL
+- **Auth**: Mana Core Auth Service (centralized)
+- **Database**: PostgreSQL (voxel_lava database)
+
+## Architecture
+
+### Backend API Endpoints
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/api/health` | GET | No | Health check |
+| `/api/levels/public` | GET | No | List public levels (paginated) |
+| `/api/levels` | GET | Yes | List user's levels |
+| `/api/levels/:id` | GET | No | Get level by ID |
+| `/api/levels` | POST | Yes | Create new level |
+| `/api/levels/:id` | PUT | Yes | Update level (owner only) |
+| `/api/levels/:id` | DELETE | Yes | Delete level (owner only) |
+| `/api/levels/:id/like` | POST | Yes | Toggle like |
+| `/api/levels/:id/liked` | GET | Yes | Check if liked |
+| `/api/levels/:id/play` | POST | No | Record play attempt |
+| `/api/levels/:id/leaderboard` | GET | No | Get top completions |
+
+### Database Schema
+
+**levels** - Main level storage
+- `id`, `name`, `description`, `userId`
+- `voxelData` (JSONB) - Block data
+- `spawnPoint`, `worldSize` (JSONB)
+- `isPublic`, `playCount`, `likesCount`
+- `difficulty`, `tags`, `thumbnailUrl`
+
+**level_likes** - Like tracking (unique per user/level)
+
+**level_plays** - Play statistics and leaderboard data
+
+### Block Types
+
+- `grass` - Standard ground block
+- `lava` - Deadly, player sinks and respawns
+- `ice` - Slippery surface
+- `goal` - Level completion trigger
+- `spawn` - Player spawn point
+- `fragile` - Breaks after stepping on
+- `trampoline` - Bounces player
+
+## Environment Variables
+
+### Backend (.env)
+```
+DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/voxel_lava
+MANA_CORE_AUTH_URL=http://localhost:3001
+PORT=3010
+```
+
+### Web (.env)
+```
+PUBLIC_VOXEL_LAVA_API_URL=http://localhost:3010
+PUBLIC_MANA_CORE_AUTH_URL=http://localhost:3001
+```
+
+## Development Setup
+
+1. Start Docker infrastructure:
+   ```bash
+   pnpm docker:up
+   ```
+
+2. Push database schema:
+   ```bash
+   pnpm voxel-lava:db:push
+   ```
+
+3. Start development:
+   ```bash
+   pnpm voxel-lava:dev
+   ```
+
+4. Open http://localhost:5180
+
+## Code Style Guidelines
+
+- **TypeScript**: Strict typing
+- **Web**: Svelte 5 runes mode
+- **Styling**: Tailwind CSS
+- **Formatting**: Prettier with 2 space indentation
+
+## Important Notes
+
+1. **Three.js Game Logic**: Located in `apps/web/src/lib/` - PlayerController.ts, BlockTypes.ts
+2. **Auth**: Uses Mana Core Auth Service - tokens stored in localStorage
+3. **Voxel Data**: Stored as JSONB with position keys (e.g., "1,2,3")
+4. **No PocketBase**: Migrated to NestJS + PostgreSQL backend