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)

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)

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 and backend/.env configured.

# 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

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

4.9 KiB Raw Permalink Blame History