CLAUDE.md Configuration Guide

/init

# Project Name

## Overview
Brief description of the project's purpose and tech stack.

## Tech Stack

- Runtime: Node.js 20
- Framework: Next.js 15
- Styling: Tailwind CSS
- Database: PostgreSQL + Prisma

## Common Commands

- Start dev server: `npm run dev`
- Run tests: `npm test`
- Build for production: `npm run build`
- Lint code: `npm run lint`

## Coding Conventions

- Use TypeScript; no `any` types allowed
- Components use functional style
- Styling with Tailwind only — no inline styles
- Commit message format: `feat:` / `fix:` / `docs:` prefixes, etc.

## Project Structure

- `src/app/` — Next.js App Router pages
- `src/components/` — Reusable components
- `src/lib/` — Utility functions
- `prisma/` — Database schema and migrations

## Notes

- Do not modify `prisma/migrations/` — only create new migrations
- All API routes are under `src/app/api/`
- Image assets go in `public/images/`

## Package Management
Use pnpm — do not use npm or yarn.
Install dependencies: `pnpm install`
Add a dependency: `pnpm add <package>`

## Testing

- Unit tests: `vitest`, files end in `.test.ts`
- E2E tests: `playwright`, located in `tests/e2e/`
- Run unit tests: `pnpm test:unit`
- Run E2E: `pnpm test:e2e`
- New features must include tests

## Prohibited Actions

- Do not use `console.log` — use the project's `logger` module instead
- Do not modify `package-lock.json` directly
- Do not commit directly to `main` — use feature branches

## Architecture Overview
This project follows Hexagonal Architecture:

- `domain/` — Business logic, no external framework dependencies
- `application/` — Use cases, coordinating domain and infrastructure
- `infrastructure/` — External adapters for databases, HTTP, etc.
- `interfaces/` — Entry points such as web controllers and CLI

New features should follow this layering — do not introduce external dependencies in the domain layer.

## Further Reading

- API documentation: `docs/api.md`
- Deployment process: `docs/deploy.md`
- Database schema: `prisma/schema.prisma`

# MyApp Frontend

## Tech Stack

- React 19 + TypeScript 5.x
- Build tool: Vite 6
- Styling: Tailwind CSS v4 (utility-first, no inline styles)
- State management: Zustand (global), TanStack Query (server state)
- Routing: React Router v7
- Testing: Vitest + Testing Library + MSW

## Commands

- Dev: `pnpm dev` (port 3000)
- Test: `pnpm test` (Vitest watch mode)
- Single run: `pnpm test:run`
- Build: `pnpm build`
- Lint: `pnpm lint` (ESLint + Prettier)
- Type check: `pnpm typecheck`

## Coding Conventions

- Components: functional components + Hooks, no class components
- Props: define with `interface` (not `type`)
- File names: components in PascalCase (UserProfile.tsx), utilities in camelCase (formatDate.ts)
- Import order: React → third-party → internal → styles
- No `any` type; explicit type annotations are required
- Async work goes through TanStack Query, not direct `useEffect` + `fetch`

## Project Structure

- src/components/ — reusable UI components
- src/pages/ — route pages
- src/hooks/ — custom Hooks
- src/api/ — API request wrappers (TanStack Query queryFn)
- src/stores/ — Zustand stores
- src/lib/ — utility functions
- src/types/ — global type definitions

## Notes

- Package manager: pnpm (not npm or yarn)
- Node.js 22+
- All API requests go through src/api/client.ts (with interceptors)
- Images live in public/images/, referenced via the /images/ path

# MyApp Backend

## Tech Stack

- Python 3.12 + FastAPI
- ORM: SQLAlchemy 2.0 (async) + Alembic migrations
- Database: PostgreSQL 16
- Cache: Redis 7
- Testing: pytest + httpx + factory_boy

## Commands

- Dev: `uvicorn app.main:app --reload --port 8000`
- Test: `pytest -xvs`
- Migrate: `alembic upgrade head`
- New migration: `alembic revision --autogenerate -m "description"`
- Lint: `ruff check .`
- Format: `ruff format .`
- Type check: `mypy app/`

## Coding Conventions

- Type hints: all function parameters and return values must have type hints
- async/await: all I/O operations use async
- Pydantic v2: request/response schemas use Pydantic BaseModel
- Dependency injection: inject database connections, auth, etc. via FastAPI Depends()
- Error handling: business exceptions inherit from app.exceptions.AppError

## Project Structure

- app/main.py — application entry point
- app/api/ — routes (one file per resource)
- app/models/ — SQLAlchemy models
- app/schemas/ — Pydantic schemas
- app/services/ — business logic
- app/core/ — config, database, security, and other core modules
- tests/ — test files (mirror the app/ structure)
- alembic/ — database migrations

## Notes

- Do not modify existing migration files under alembic/versions/
- The .env file is not committed to Git; it is loaded via the Settings class in app/core/config.py
- Virtual environment: `python -m venv venv && source venv/bin/activate`

# MyService

## Tech Stack

- Go 1.23
- HTTP framework: Echo v4
- Database: PostgreSQL + sqlc (type-safe SQL)
- Message queue: NATS JetStream
- Containerization: Docker + docker-compose

## Commands

- Run: `go run ./cmd/server`
- Test: `go test ./...`
- Build: `go build -o bin/server ./cmd/server`
- Generate sqlc: `sqlc generate`
- Lint: `golangci-lint run`

## Coding Conventions

- Error handling: always check err, never ignore it with _
- Interface naming: single-method interfaces take the -er suffix (Reader, Writer)
- Package naming: lowercase words, no underscores
- Logging: use slog for structured logging
- Context: pass context.Context as the first parameter of every function

## Project Structure (standard Go layout)

- cmd/server/ — main program entry point
- internal/handler/ — HTTP handlers
- internal/service/ — business logic
- internal/repository/ — data access layer
- internal/model/ — data models
- sql/ — SQL query files (used by sqlc)

# MyPlatform Monorepo

## Tech Stack

- Package management: pnpm workspace
- Build system: Turborepo
- Language: TypeScript across the stack

## Commands

- Global dev: `pnpm dev`
- Global test: `pnpm test`
- Global build: `pnpm build`
- Single-package dev: `pnpm --filter @myplatform/web dev`
- Add a dependency: `pnpm --filter @myplatform/api add express`

## Package Structure

- apps/web/ — Next.js frontend
- apps/api/ — Express backend
- apps/admin/ — admin dashboard
- packages/ui/ — shared UI component library
- packages/config/ — shared config (eslint, tsconfig)
- packages/types/ — shared type definitions

## Notes

- Shared code goes in packages/; do not import directly between apps
- When creating a new package, follow the format of packages/ui/package.json
- Turborepo cache: build artifacts are cached in node_modules/.cache/turbo

# ML Pipeline

## Tech Stack

- Python 3.12
- Framework: PyTorch 2.5 + Lightning
- Data processing: Polars (not Pandas)
- Experiment tracking: MLflow
- Dependency management: uv

## Commands

- Train: `python -m src.train --config configs/experiment.yaml`
- Evaluate: `python -m src.evaluate --checkpoint runs/latest`
- Preprocess data: `python -m src.preprocess --data-dir data/raw`
- Jupyter: `jupyter lab`
- Test: `pytest tests/`

## Coding Conventions

- Use YAML for configuration (do not hard-code hyperparameters)
- Use Polars for data processing (faster than Pandas, type-safe)
- All experiments must be logged to MLflow
- Notebooks are for exploration only; production code must live in src/

## Project Structure

- configs/ — experiment configuration YAML
- data/raw/ — raw data (not committed to Git, managed with DVC)
- data/processed/ — processed data
- src/ — core code (model, data, train, evaluate)
- notebooks/ — exploratory analysis
- runs/ — training outputs (checkpoints, logs)

# Project Rules

@AGENTS.md

## Claude Code specifics

- Use /model to switch to Opus 4.8 for large refactors
- Reference docs/architecture.md instead of pasting it