# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

**MAIN RULE:** DON'T MAKE UP ANYTHING. If unsure, verify via project documentation, MCP tools, web search, or ask for clarification.

## Development Commands

### Backend (from `backend/`)
```bash
npm run dev           # Development server with hot reload (tsx watch)
npm run verify        # Run typecheck + lint + tests (use before commits)
npm run typecheck     # TypeScript check only
npm run lint          # ESLint only
npm run test          # Node test runner (tsx --test)
npm run build         # Production build → dist/

# Database
npm run db:migrate    # Run pending migrations
npm run db:seed       # Run seeders
npm run db:reset      # Drop all → migrate → seed (destroys data)
npm run start         # migrate + seed + watch (dev startup)
```

### Frontend (from `frontend/`)
```bash
npm run dev           # Vite dev server (port 3000)
npm run build         # Typecheck + Vite production build
npm run typecheck     # TypeScript check only
npm run lint          # ESLint only
npm run test          # Vitest unit tests
npm run test:e2e      # Playwright smoke tests (no backend)
npm run test:e2e:content  # Playwright tests (requires backend running)
```

### Root-level
```bash
npm run build:production   # Build both frontend and backend
npm run start:production   # Start production backend (serves API + SPA)
```

### Docker (from `docker/`)
```bash
docker compose up --build  # PostgreSQL + app on localhost:8080
docker compose down -v     # Stop and remove (including DB data)
```

### Quick Start (Dev Mode)

Prerequisites: PostgreSQL running locally with database `schoolchain_dev` and `backend/.env` configured.

```bash
# Terminal 1 - Backend (port 8080)
cd backend
export $(grep -v '^#' .env | xargs) && npm run dev

# Terminal 2 - Frontend (port 3000)
cd frontend
npm run dev
```

- Frontend: http://localhost:3000
- Backend API: http://localhost:8080/api-docs/
- Login: `admin@flatlogic.com` / `flatlogicAdmin123!`

Note: Use `npm run start` (not `npm run dev`) for first run to execute migrations and seeders.

## Architecture

### Three-Layer Pattern (Both Frontend and Backend)

**Backend** (`backend/src/`):
```
API Layer     → routes/*.ts, api/controllers/*.ts, middlewares/*.ts
Business Layer → services/*.ts (static class methods)
Data Layer    → db/api/*.ts (repositories), db/models/*.ts (Sequelize)
```

**Frontend** (`frontend/src/`):
```
View Layer    → pages/, components/
Business Layer → business/<module>/ (hooks, mappers, selectors)
Data Layer    → shared/api/*.ts, shared/types/*.ts
```

Import direction: `API → Business → Data`. Never skip layers. Cross-cutting code lives in `shared/` and can be imported by any layer.

### Key Patterns

**CRUD Modules**: Most entities use shared factories:
- `services/shared/crud-service.ts` → one-line service config
- `api/controllers/shared/crud-controller.ts` → one-line controller config
- `api/http/crud-router.ts` → one-line router config

**Error Handling**: Throw `AppError` subclasses from `shared/errors/`. The terminal `error-handler` middleware formats responses.

**Authentication**: Backend-owned HttpOnly cookie auth. Frontend uses `AuthContext` as a thin provider; refresh/retry logic in `shared/api/httpClient.ts`.

**Import Aliases**: Use `@/*` for all imports (maps to `./src/*` in both projects).

## Working Principles

1. **Check docs first**: Read relevant docs before starting (see Documentation Entry Points below)
2. **Minimal changes**: Only update necessary files, prefer simple robust solutions
3. **TypeScript strict mode**: No `any` types, never disable linter/TypeScript, no type casting
4. **Concise comments**: Explain "why" not "what"
5. **No over-engineering**: Build for small SaaS. Simplest robust solution. No enterprise patterns unless required.
6. **Centralized exceptions only**: Use `AppError` subclasses from `shared/errors/`
7. **Avoid hardcoded constants**: Add to `backend/src/shared/constants/` or `frontend/src/shared/constants/`
8. **Documentation matters**: Update docs after each task; create docs for new modules
9. **Tests matter**: Update tests after each task; create tests for new functionality

## Documentation Entry Points

- Frontend architecture: `frontend/docs/frontend-architecture.md`
- Backend architecture: `backend/docs/backend-architecture.md`
- Database schema: `backend/docs/database-schema.md` (regenerate after schema changes)
- Integration plan: `docs/full-integration-refactor-plan.md`
- VM deployment: `docs/deployment-vm.md`
- Docker deployment: `docs/deployment-docker.md`

## Tech Stack

- **Backend**: Node 24, Express 5, Sequelize 6, TypeScript 6, PostgreSQL
- **Frontend**: React 19, Vite 8, TypeScript 6, Tailwind 4, React Query, Vitest, Playwright
- **Both**: ESM modules, strict TypeScript, path aliases (`@/*`)

## MCP Servers Available

- `github` - GitHub operations
- `chrome-devtools` - Browser DevTools
- `posthog` - Analytics (project: TRO Matcher)