autohero/CLAUDE.md

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.