School Administration System

A Node.js/TypeScript REST API for managing teachers, students, classes and subjects.

Node.js v22 (LTS). Any v18+ should also work.

• Node.js v22
• Docker & Docker Compose

# 1. Install dependencies
npm install

# 2. Start MySQL and the external student service via Docker
npm run start:services

# 3. Start the development server (auto-restarts on file changes)
npm run start:dev

The API is available at http://localhost:3000.

Note: start:services waits for Docker containers to start. If the app fails to connect on first launch it will retry up to 20 times (3 s apart).

Copy .env.sample to .env and adjust as needed. Defaults work out of the box with the provided docker-compose.yml.

Upload a CSV file to create, update or delete teachers/students/classes.

Content-Type: multipart/form-data
Field name:   data

• Success: 204 No Content
• Error: 400 Bad Request / 500 Internal Server Error

Returns a paginated, alphanumerically sorted list of all students (internal and external) enrolled in the given class.

Query params:

Response 200:

{
  "count": 42,
  "students": [
    { "id": 1, "name": "Alice", "email": "alice@school.com", "isExternal": false },
    { "id": 7, "name": "Bob",   "email": "bob@ext.com",      "isExternal": true  }
  ]
}

• Error: 400 Bad Request / 500 Internal Server Error

Updates the display name of an existing class.

Body:

{ "className": "P1 Excellence" }

• Success: 204 No Content
• Error: 400 Bad Request / 500 Internal Server Error

Returns each teacher's teaching workload grouped by subject.

Response 200:

{
  "Teacher One": [
    { "subjectCode": "MATHS", "subjectName": "Mathematics", "numberOfClasses": 3 }
  ],
  "Teacher Two": [
    { "subjectCode": "ENG", "subjectName": "English", "numberOfClasses": 1 }
  ]
}

• Error: 500 Internal Server Error

Returns 200 OK when the server is running.

npm test

Tests use Jest + ts-jest. All services are tested with mocked dependencies (no live database or network required).