# Repository Guidelines

## Project Structure & Module Organization
This is an Elixir umbrella app with multiple sub-apps under `apps/`.
- `apps/codebattle/`: Phoenix app with Elixir code in `apps/codebattle/lib/`, tests in `apps/codebattle/test/`, and frontend assets in `apps/codebattle/assets/`.
- `apps/runner/`: task runner service and language images under `apps/runner/images/`.
- `apps/phoenix_gon/`, `config/`, `priv/`, and top-level `mix.exs` provide shared library/config and releases.

## Main Contexts & Helpers
Core domains expose context modules for public APIs:
- `Codebattle.Game.Context` (`apps/codebattle/lib/codebattle/game/context.ex`): game lifecycle, live game access, and player actions.
- `Codebattle.Tournament.Context` (`apps/codebattle/lib/codebattle/tournament/context.ex`): tournament CRUD, live supervision, and access checks.
- `Codebattle.Tournament.Round.Context` (`apps/codebattle/lib/codebattle/tournament/round/context.ex`): round construction and persistence.
- `Codebattle.Playbook.Context` (`apps/codebattle/lib/codebattle/playbook/context.ex`): game replay records and storage.
- `Codebattle.Event.Context` (`apps/codebattle/lib/codebattle/event/context.ex`): event stages and tournament bootstrapping.
- `Codebattle.Bot.Context` (`apps/codebattle/lib/codebattle/bot/context.ex`): bot selection and runtime start.

Helper modules live alongside their domains:
- Game helpers: `apps/codebattle/lib/codebattle/game/helpers.ex`; tournament helpers: `apps/codebattle/lib/codebattle/tournament/helpers.ex`.
- Operational utilities: `apps/codebattle/lib/codebattle/utils/` (populate tasks/users/clans, release helpers).

## Build, Test, and Development Commands
Use the Makefile targets for common workflows:
- `make format` / `make lint`: format or check Elixir formatting.
- `make credo`: run Credo static analysis.
- `make lint-js`: OXC (`oxlint`) for frontend assets.
- `make server`: start Phoenix (`iex -S mix phx.server`).
- `make test`: ExUnit + coveralls JSON.
- `make test-code-checkers`: image executor tests with `CODEBATTLE_EXECUTOR=local`.

For frontend-only tasks in `apps/codebattle/`:
- `pnpm run dev`: Vite dev server.
- `pnpm run build`: production build.
- `pnpm run test`: Jest tests.

## Coding Style & Naming Conventions
- Elixir formatting is enforced via `mix format` (see `.formatter.exs`).
- Credo rules live in `.credo.exs` (120-char line limit).
- JavaScript/React linting uses OXC (`oxlint`) via `pnpm run lint`.
- Naming: descriptive Elixir modules; `camelCase`/`PascalCase` for JS files and components.

## Testing Guidelines
- ExUnit tests live in `apps/*/test/`; coverage uses ExCoveralls with a 60% threshold.
- Frontend tests use Jest in `apps/codebattle/`.
- Name tests after the module/component under test (e.g., `user_stats_test.exs`, `UserStats.test.jsx`).

## Commit & Pull Request Guidelines
- Recent commits use short, imperative summaries (e.g., "Fix editor", "Update logo").
- Keep commits focused; include test results when relevant.
- PRs should describe the change, list test commands run, and attach screenshots for UI updates.

## Configuration & Runtime Notes
- Releases are defined in `mix.exs` for `codebattle` and `runner`; runner images build via Makefiles in `apps/runner/images/`.