layers/structure.md

Project Structure

AI-assisted iterative game development environment with real-time feedback

Stack

• Runtime: Bun
• Language: TypeScript
• UI Framework: Svelte
• Game Engine: VibeGame (3D physics, ECS)
• Code Editor: Monaco Editor
• AI Agent: LangGraph.js with Hugging Face Inference
• WebSocket: ws (for real-time communication)
• Build: Vite
• Animation: GSAP (bundled with VibeGame)
• Physics: Rapier (via VibeGame)
• Rendering: Three.js (via VibeGame)

Commands

• bun dev - Development server with hot reload on port 7860
• bun run build - Build for production
• bun run preview - Preview production build
• bun run check - TypeScript + Svelte type checking
• bun run lint - ESLint code quality check
• bun run format - Auto-format with Prettier
• bun run validate - Complete validation (format, lint, type check)

Layout

vibegame/
├── CLAUDE.md          # Global context (Tier 0)
├── PLAN.md           # Development roadmap
├── layers/
│   ├── structure.md   # Project structure (Tier 1)
│   └── context-template.md
├── src/
│   ├── main.ts        # Svelte app initialization
│   ├── App.svelte     # Root UI component (declarative)
│   └── lib/
│       ├── stores/        # State management
│       ├── services/      # Business logic
│       ├── server/        # WebSocket server & agent
│       ├── components/    # UI components
│       │   ├── chat/      # AI chat interface
│       │   ├── console/
│       │   ├── editor/
│       │   ├── game/
│       │   └── layout/
│       └── config/        # Configuration
├── index.html         # Entry point
├── package.json       # Dependencies and scripts
├── tsconfig.json      # TypeScript configuration
├── vite.config.ts     # Vite + Svelte + VibeGame config
├── bun.lock          # Dependency lock file
├── llms.txt          # VibeGame documentation
└── README.md

Architecture

Three-layer architecture: UI (Svelte) → Agent (Hugging Face) → Game (VibeGame)

• UI Layer: Svelte components for chat, code editing, console display
• Agent Layer: LangGraph.js agent via WebSocket with Read/Write tools
• Game Layer: VibeGame ECS with declarative XML scene definition

Entry points

• Main entry: index.html (HTML shell)
• UI entry: src/main.ts (Svelte app mount)
• App root: src/App.svelte (Component tree root)
• Game definition: <world> tag in editor (Live-editable XML)

Naming Conventions

TypeScript/Web standards with Svelte and ECS conventions

• Files: kebab-case for utilities, PascalCase for components (e.g., Chat.svelte, mcp-tools.js)
• Directories: lowercase (e.g., src/, components/, stores/)
• Svelte components: PascalCase (e.g., Editor.svelte, Preview.svelte)
• Stores: camelCase (e.g., gameState, consoleMessages)
• ECS Components: PascalCase (e.g., Health, Transform)
• Systems: PascalCase with "System" suffix (e.g., HealthSystem)

Configuration

• TypeScript: tsconfig.json (Strict mode, ESNext target)
• Build: vite.config.ts (Vite with Svelte, VibeGame, WebSocket plugins)
• Dependencies: package.json (Svelte, VibeGame, Monaco, Hugging Face, ws)
• Game Scene: Live-editable in Monaco editor

Where to add code

• UI components → src/lib/components/[feature]/[Component].svelte
• State management → src/lib/stores/[store].ts
• Business logic → src/lib/services/[service].ts
• Server/Agent logic → src/lib/server/[module].ts
• Configuration → src/lib/config/[config].ts
• Game entities → XML in Monaco editor
• Custom ECS components → src/lib/game/components/[Component].ts
• Custom systems → src/lib/game/systems/[System].ts