# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

AutoHero is an isometric browser-based idle/incremental combat game designed for Telegram Mini Apps. The project uses a multi-agent development workflow with 8 specialized Claude agents.

## Tech Stack

- **Backend**: Go (game server, REST + WebSocket APIs)
- **Frontend**: React + TypeScript with PixiJS for isometric rendering
- **Database**: PostgreSQL (primary), Redis (caching/sessions/pub-sub)
- **Platform**: Telegram Mini Apps (`window.Telegram.WebApp` SDK)
- **Target**: 60 FPS on mid-range mobile devices, 100k concurrent users

## Architecture

### Backend (Go)
- Standard Go project layout: `cmd/`, `internal/`, `pkg/`
- Tick-based game loop engine with configurable tick rate
- Combat system using min-heap ordered by `next_attack_at` timestamps
- Buff/debuff modifiers as middleware in the damage pipeline
- WebSocket hub pattern (register/unregister channels, per-connection read/write goroutines)
- Offline simulation via deterministic cron-based batch processing
- Structured logging (slog or zerolog), context propagation everywhere

### Frontend (React + TypeScript)
- PixiJS canvas for game world, React DOM overlay for UI
- Fixed-timestep game loop with `requestAnimationFrame`
- Folder structure: `/game` (engine/rendering), `/ui` (React components), `/network` (WS), `/shared` (types)
- WebSocket client with auto-reconnect, heartbeat, and message queuing
- TypeScript strict mode, functional React components with hooks

### Communication
- REST for CRUD/state queries
- WebSocket for real-time combat events and state pushes
- Binary protocols (MessagePack/Protobuf) for performance-critical paths

## Agent System

Eight specialized agents are defined in `.claude/agents/`:

| Agent | Role |
|-------|------|
| `system-architect` | Service design, scaling, tech selection |
| `tech-lead` | Prioritization, MVP scope, speed vs quality |
| `backend-engineer-go` | Go game server implementation |
| `frontend-game-engineer` | PixiJS rendering, UI, WebSocket client |
| `game-designer` | Mechanics, balance, progression, retention |
| `qa-game-engineer` | Test design, combat edge cases, load testing |
| `code-design-reviewer` | Code quality, overengineering detection |
| `devops-infra` | CI/CD, Docker, monitoring, cloud |

Agents maintain persistent memory in `.claude/agent-memory/{agent-name}/`.

## Key Design Decisions

- **Go concurrency**: Prefer channels over shared memory; keep mutex critical sections minimal. Always use `-race` flag in tests.
- **Idle game philosophy**: Simple under the hood; performance-first for frame budget; mobile-first for touch/small screens.
- **MVP approach**: Optimize for speed, accept tactical debt (documented), but invest in quality for auth, data model, and payments.
- **Boring technology**: Prefer proven tech unless there's a compelling reason. The best tech is the one the team knows.
- **Contract-first**: Define API contracts early to unblock parallel backend/frontend work.