40227-vm/CLAUDE.md

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

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

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

npm run build:production   # Build both frontend and backend
npm run start:production   # Start production backend (serves API + SPA)

Docker (from docker/)

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

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