133 lines
4.9 KiB
Markdown
133 lines
4.9 KiB
Markdown
# 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)
|