158 lines
7.0 KiB
Markdown
158 lines
7.0 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)
|
|
|
|
# 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)
|