School ERP Code Guide

Development assistant for the SchoolERP_v2 codebase — a modular, activity-driven school management system.

Primary Documentation Authority

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

Architecture Overview

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

```

Step-by-Step Activity Implementation

When implementing any activity, follow this exact sequence:

1. Read Activity Specification

2. Check Dependencies

3. Verify OpenAPI Contract

4. Create DTOs

In `src/modules/{module}/dtos.ts`:

5. Implement Data Layer

In `src/modules/{module}/repos.ts`:

6. Implement Business Logic

In `src/modules/{module}/services.ts`:

7. Implement Controller

In `src/modules/{module}/controllers.ts`:

- Success: `{ "success": true, "data": <payload> }`

- Error: `{ "success": false, "error": { "code": "ERROR_CODE", "message": "...", "details": {}, "traceId": "..." } }`

8. Add Contract Test

In `tests/contract/cases.json`:

9. Run Tests

```bash

npm run test:contract # Contract tests

npm run verify:tracker # Implementation consistency check

```

All tests must pass before committing.

10. Commit Changes

Use format: `feat(ACTIVITY-ID): description`

Example: `feat(FEES-05-006): implement generate fee receipt`

Development Commands

Build & Run

```bash

npm run build # Compile TypeScript → dist/

npm run dev # Development server (ts-node)

npm start # Production server (compiled JS)

```

Testing

```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

```

Load Testing (k6)

```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

```

Mandatory Patterns

Error Handling

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> }`

DTO Naming

RBAC Enforcement

Audit Logging

Emit events for sensitive operations:

Database Rules

- Master DB: `system_*`, `trusts`, `migration_versions`

- Trust DB: `schools`, `users`, `students`, `fee_*`, `attendance_*`, etc.

Quality Standards

TypeScript

Security

Frontend (EJS)

Process Management Rules

**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

Key Reference Files

Deployment

Single VM deployment via `docker-compose.yml`:

Important Rules

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

Before Starting Work

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