autohero/.claude/agent-memory/backend-engineer-go/project_backend_skeleton.md

name	description	type
Backend skeleton and wiring	Go backend structure as of 2026-03-27 — engine wired to real combat, auth middleware, CORS, camelCase JSON, new endpoints	project

Backend skeleton was created on 2026-03-27, with critical wiring fixes applied on 2026-03-28:

• Module: github.com/denisovdennis/autohero, Go 1.23
• Entry point: backend/cmd/server/main.go — config, DB/Redis connect, game engine, WS hub, HTTP server with graceful shutdown
• Config: env vars (DB_*, REDIS_ADDR, SERVER_PORT, BOT_TOKEN) with local dev defaults
• Models: Hero, Enemy (13 types + templates), Weapon (daggers/sword/axe), Armor (light/medium/heavy), Buff (8 types), Debuff (6 types), CombatState + AttackQueue (min-heap), Loot system
• All model JSON tags use camelCase (maxHp, telegramId, critChance, etc.) to match frontend expectations
• CombatState has a Hero *Hero field (json:"-") so engine can reference hero during combat
• Game engine: tick-based loop (100ms/10Hz), attack scheduling via container/heap, uses real ProcessAttack/ProcessEnemyAttack/CheckDeath from combat.go
• Engine handles hero death: emits "death" event, sets hero state to Dead, removes combat
• Combat: full damage pipeline with buffs/debuffs, crit, dodge, stun, shield, lifesteal, etc.
• Auth: handler/auth.go — Telegram initData HMAC-SHA256 validation, TelegramAuthMiddleware, POST /api/v1/auth/telegram
• Handlers: GET /health, GET /api/v1/hero, POST /api/v1/hero/buff/{buffType}, POST /api/v1/hero/revive, GET /api/v1/hero/loot, GET /api/v1/weapons, GET /api/v1/armor, GET /ws
• Router: router.Deps struct takes Engine, Hub, PgPool, BotToken, Logger. CORS middleware allows all origins (dev mode).
• Auth middleware is wired but commented out for dev convenience.
• Storage: pgx pool (20 max conns), go-redis client. pgPool passed to router deps.
• Hero model has: PositionX, PositionY (float64), Potions (int) — added 2026-03-27
• HeroStore has SavePosition(ctx, heroID, x, y) for lightweight position updates
• LogStore (storage/log_store.go): Add(), GetRecent() for adventure_log table
• GameHandler constructor takes logStore as 3rd argument: NewGameHandler(engine, heroStore, logStore, worldSvc, logger)
• New endpoints: GET /api/v1/hero/log, POST /api/v1/hero/use-potion
• Loot system: 25% potion drop chance, potions heal 30% maxHP
• Offline simulation: uses potions when HP < 30%, tracks loot drops, generates detailed log
• Auto-equip: logs weapon/armor changes to adventure log
• Migration 000004: hero position_x/position_y, potions column, adventure_log table

Why: First major wiring pass connects all backend systems end-to-end. Frontend can now hit all needed endpoints.

How to apply: All new backend code should follow this package structure. The router.Deps pattern is the dependency injection point. Auth middleware can be re-enabled when BOT_TOKEN is provided.