project-structure

name	project-structure
description	The bombdog repository's structure and stack conventions. Covers the top-level layout, the Next.js App Router structure under src/app, where unit tests and Playwright e2e tests live, the tooling stack (npm, Biome, Vitest, Playwright), and the agent-harness files under .claude.
when_to_use	Use when navigating the repository, locating a file, deciding where a new module/route/component/test belongs, or checking stack and directory conventions — even when the user only mentions "where does X go", file placement, the folder layout, or the project's stack.
user-invocable	false

Project Structure

Apply this skill to navigate bombdog and to place new files consistently. bombdog is a Next.js (App Router) + TypeScript web app.

Stack

• Runtime / framework: Next.js 16 (App Router), React 19.
• Language: TypeScript (strict). Import alias @/* maps to src/*.
• Package manager: npm (package-lock.json is the source of truth). Node version pinned in .nvmrc.
• Lint + format: Biome (biome.json). Tab indentation, double quotes.
• Unit tests: Vitest + Testing Library (jsdom environment).
• E2E tests: Playwright (Chromium).
• Styling: CSS Modules (*.module.css). No CSS framework.

Top-Level Layout

Path	Owns
src/app/	App Router routes, layout.tsx, page.tsx, and the global CSS trio layers.css / globals.css / variables.css
src/components/primitives/<name>/	Strictly domain-agnostic primitives (button, bottom-sheet, select-field, segmented-picker, toggle-grid, chip, …), one kebab-case folder each, colocating <name>.tsx, <name>.module.css, and <name>.spec.tsx
src/components/tracker/<name>/	Domain components — store/game-rule compositions and thin domain wrappers over primitives (wire-pad, wire-chip, player-picker, …) — with the same colocation
src/hooks/	Reusable hook functions (use-<name>.ts) binding domain logic to React state + colocated *.spec.ts(x)
src/lib/	Non-UI application code (kebab-case: tracker-store.ts, idb-storage.ts, game.ts, move-draft.ts, types.ts) + colocated *.spec.ts
e2e/tests/	Playwright end-to-end specs (*.test.ts)
e2e/helpers/	Reusable e2e helpers (page setup, chained-locator shortcuts)
public/	Static assets served from the site root
.claude/	Claude Code harness binding (hooks, settings)
.claude/skills/	Project skill library, routed from AGENTS.md
biome.json, vitest.config.ts, playwright.config.ts, next.config.ts,

File Placement

New files follow fixed placement rules by kind — routes, components, non-UI modules, and their colocated tests each have a home.

Guidelines:

• MUST use kebab-case for all file and folder names (move-composer/move-composer.tsx).
• MUST place routes under src/app/ following App Router conventions (page.tsx, layout.tsx, loading.tsx, error.tsx, route segment folders).
• MUST place components per the tier decision in the project's React guidelines — strictly domain-agnostic primitives under src/components/primitives/<name>/, domain components under src/components/tracker/<name>/ — and non-UI modules under src/lib/. That skill owns the tier semantics, the primitives import rule, and the split/promotion strategy.
• MUST place reusable hook functions under src/hooks/ as use-<name>.ts; when logic belongs in a hook vs src/lib vs the component is owned by the project's React guidelines.
• MUST colocate a unit test next to its subject as <name>.spec.ts(x); Vitest picks up src/**/*.{test,spec}.{ts,tsx}.
• MUST place end-to-end specs under e2e/tests/ as <name>.test.ts (Playwright testDir is e2e/tests) and shared e2e helpers under e2e/helpers/.
• MUST colocate a component's styles as <name>.module.css and import them as css.
• SHOULD use the @/ alias for imports from src/ rather than long relative paths.