# 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)

# VM Database Reset (requires platform credentials)
# 1. npm ci (install deps)
# 2. Get credentials: pm2 env 1 | grep DB_PASS && cat ~/executor/.env | grep DB_
# 3. DB_HOST=... DB_NAME=... DB_USER=... DB_PASS=... npm run db:reset
# 4. pm2 restart backend-dev frontend-dev --update-env
```

### 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)
npm run test:e2e:content -- --grep "accessibility"  # Accessibility tests only
```

### 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` (user: `postgres`, password: `postgres`).

```bash
# Terminal 1 - Backend (port 8080)
cd backend && npm run dev

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

- Frontend: http://localhost:3000
- Backend API: http://localhost:8080/api-docs/

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

### Seed Users (one per role)

Seeded by `backend/src/db/seeders/*` from `shared/constants/seed-fixtures.ts`. Passwords are
hardcoded in the seeder (see table below).

| Email | Name | Role | Scope | Password |
|---|---|---|---|---|
| `admin@flatlogic.com` | Mr. Alex Morgan | `super_admin` | system | `flatlogicAdmin123!` |
| `system_admin@flatlogic.com` | Ms. Jordan Chen | `system_admin` | system | `flatlogicAdmin123!` |
| `owner@flatlogic.com` | Mrs. Patricia Hayes | `owner` | organization | `flatlogicUser123!` |
| `superintendent@flatlogic.com` | Dr. Michael Torres | `superintendent` | organization | `flatlogicUser123!` |
| `director@flatlogic.com` | Dr. Sarah Williams | `director` | campus | `flatlogicUser123!` |
| `office_manager@flatlogic.com` | Ms. Lisa Park | `office_manager` | campus | `flatlogicUser123!` |
| `teacher@flatlogic.com` | Mrs. Emily Johnson | `teacher` | campus | `flatlogicUser123!` |
| `support_staff@flatlogic.com` | Mr. Marcus Davis | `support_staff` | campus | `flatlogicUser123!` |
| `student@flatlogic.com` | Emma Clark | `student` | external | `flatlogicUser123!` |
| `guardian@flatlogic.com` | Mr. Robert Clark | `guardian` | external | `flatlogicUser123!` |

All belong to the seeded company **Demo Academy**; campus-scoped/external users are on the **Tigers** campus. `super_admin`/`system_admin` carry `globalAccess` (no org/campus).

## 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
10. **English only**: All documentation, comments, code, and content must be in English (except TODOs or internal plans)

## 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)
- **Backlog / remaining work: `docs/backlog.md`** — the single source for deferred work and open gaps (endpoint wiring, RBAC residuals, design-gated UIs, Phase 4/5 items, file/test/a11y). Consult it before starting work or closing gaps, and keep it updated. (The former sequenced integration plan is retired; its history is in git.)
- 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)
