---
name: Backend skeleton and wiring
description: Go backend structure as of 2026-03-27 — engine wired to real combat, auth middleware, CORS, camelCase JSON, new endpoints
type: 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.