Development guide for a modular school management system with contract-first API design, activity-driven architecture, and strict quality patterns (TypeScript, OpenAPI, multi-tenant MySQL).
Development assistant for the SchoolERP_v2 codebase — a modular, activity-driven school management system.
**CRITICAL:** `SCHOOL_ERP_MASTER_SPECIFICATION.md` is the single source of truth. All development decisions must defer to this file. Legacy documentation in `docs/legacy_instructions/` is archived and should NOT be used.
This is a School ERP system with **66 specific activities** across 9 modules using a contract-first, activity-driven architecture.
**Tech Stack:**
**Modules:** `data`, `setup`, `auth`, `user`, `stud`, `fees`, `attd`, `rept`, `dash`, `comm`
Each module follows this exact structure:
```
src/modules/{module}/
├── controllers.ts # HTTP handlers (one per activity)
├── services.ts # Business logic
├── repos.ts # Data access (parameterized queries only)
├── dtos.ts # Zod validation schemas
├── validators.ts # Re-exports for clarity
└── index.ts # Barrel exports
```
When implementing any activity, follow this exact sequence:
In `src/modules/{module}/dtos.ts`:
In `src/modules/{module}/repos.ts`:
In `src/modules/{module}/services.ts`:
In `src/modules/{module}/controllers.ts`:
- Success: `{ "success": true, "data": <payload> }`
- Error: `{ "success": false, "error": { "code": "ERROR_CODE", "message": "...", "details": {}, "traceId": "..." } }`
In `tests/contract/cases.json`:
```bash
npm run test:contract # Contract tests
npm run verify:tracker # Implementation consistency check
```
All tests must pass before committing.
Use format: `feat(ACTIVITY-ID): description`
Example: `feat(FEES-05-006): implement generate fee receipt`
```bash
npm run build # Compile TypeScript → dist/
npm run dev # Development server (ts-node)
npm start # Production server (compiled JS)
```
```bash
npm run test:contract # Contract tests vs OpenAPI
npm run gen:contract:cases # Generate test case skeletons
npm run verify:tracker # Check implementation consistency
```
```bash
npm run load:k6:login # Login endpoint
npm run load:k6:admission # Admission flow
npm run load:k6:receipt # Fee receipt flow
npm run load:k6:attendance # Attendance endpoints
npm run load:k6:reports # Reporting endpoints
```
All endpoints must return this exact envelope:
```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human readable message",
"details": {},
"traceId": "optional"
}
}
```
Success: `{ "success": true, "data": <payload> }`
Emit events for sensitive operations:
- Master DB: `system_*`, `trusts`, `migration_versions`
- Trust DB: `schools`, `users`, `students`, `fee_*`, `attendance_*`, etc.
**CRITICAL:** Never use `taskkill //F //IM node.exe` — this kills ALL Node.js processes including the current session.
**Correct background process workflow:**
1. Start: `Bash("npm run dev", run_in_background: true)` → returns `bash_id`
2. Monitor: `BashOutput(bash_id)` to check output
3. Terminate: `KillBash(bash_id)` when done
Single VM deployment via `docker-compose.yml`:
1. **Never break Activity IDs** — immutable across all files
2. **Never invent fields/endpoints** — follow specifications exactly
3. **Never skip RBAC, validation, or audit logging**
4. **Never use raw SQL without parameters**
5. **Always validate against OpenAPI contract in tests**
6. **Follow the Master Specification** — it has final authority
1. Install dependencies: `npm i`
2. Verify database schema matches migrations
3. Read official docs for any libraries
4. Check RBAC matrix in `rbac/RBAC_MATRIX.md`
5. Consult `SCHOOL_ERP_MASTER_SPECIFICATION.md` for architecture decisions
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/school-erp-code-guide/raw