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`