NestJS API

Location: syncad/apps/api Port: 3001 Swagger: /api-docs

Modules

The API is organized into feature modules, each with its own controller and service.

src/modules/
├── school-admin/      # School admin UI endpoints
│   ├── student/
│   ├── employee/
│   ├── class/
│   ├── division/
│   ├── subject/
│   ├── attendance/
│   ├── exam/
│   ├── fee/
│   ├── announcement/
│   ├── leave/
│   ├── transport/
│   └── library/
├── parent/            # Parents app endpoints
│   ├── student/
│   ├── attendance/
│   ├── exam/
│   ├── fee/
│   ├── announcement/
│   ├── leave/
│   ├── timetable/
│   ├── message/
│   └── notification/
├── teacher/           # Teachers app endpoints
│   ├── attendance/
│   ├── exam/
│   ├── result/
│   ├── subject/
│   ├── class/
│   ├── leave/
│   ├── announcement/
│   └── notification/
├── driver/            # Driver app endpoints
│   ├── bus/
│   ├── trip/
│   ├── student/
│   └── incident/
├── bus-tracking/      # Socket.IO + REST for live tracking
├── messaging/          # Internal messaging
├── aws/               # S3 upload, SES, SNS integrations
└── super-admin/       # Cross-school admin endpoints

Key Controllers

Auth Controller

// POST /auth/send-otp
// POST /auth/verify-otp
// POST /auth/set-pin
// POST /auth/verify-pin
// POST /auth/refresh
// POST /auth/logout

School Admin Controllers

// Students
POST   /school-admin/student/create
GET    /school-admin/student/list
GET    /school-admin/student/:id
PUT    /school-admin/student/:id
DELETE /school-admin/student/:id
POST   /school-admin/student/import   // Bulk import via CSV

// Employees
POST   /school-admin/employee/create
GET    /school-admin/employee/list
GET    /school-admin/employee/:id
PUT    /school-admin/employee/:id

// Classes & Divisions
POST   /school-admin/class/create
GET    /school-admin/class/list
POST   /school-admin/division/create

// Attendance
POST   /school-admin/attendance/mark        // Bulk mark
GET    /school-admin/attendance/report      // Monthly report
GET    /school-admin/attendance/summary     // Summary view

// Exams
POST   /school-admin/exam/create
GET    /school-admin/exam/list
POST   /school-admin/exam/schedule
POST   /school-admin/exam/result/upload

// Fees
POST   /school-admin/fee/structure/create
GET    /school-admin/fee/structure/:classId
POST   /school-admin/fee/collection/record
GET    /school-admin/fee/report/:studentId
POST   /school-admin/fee/reminder/send

// Bus Tracking
POST   /school-admin/transport/bus/create
GET    /school-admin/transport/bus/list
POST   /school-admin/transport/route/create
POST   /school-admin/transport/trip/schedule

Bus Tracking Controller (REST + Socket.IO)

// REST
GET    /bus-tracking/bus/:busId/live        // Current trip status
GET    /bus-tracking/trip/:tripId/students  // Students on trip
GET    /bus-tracking/incidents/:busId        // Incident history

// Socket.IO events (emitted by driver app)
'join-bus-room'      // { schoolId, busId }
'leave-bus-room'     // { schoolId, busId }
'update-location'   // { lat, lng, speed, heading, timestamp }

Request/Response Patterns

School Admin CRUD Pattern

// POST /school-admin/{resource}/create
// Request body contains a `data` wrapper
{
  "data": {
    "firstName": "John",
    "lastName": "Doe",
    "classId": "uuid",
    // ...
  }
}

// Response
{
  "data": { "id": "uuid", ... },
  "message": "Student created successfully"
}

Error Response

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    { "field": "firstName", "message": "First name is required" }
  ]
}

Guards & Middleware

Guard	Purpose
JwtAuthGuard	Validates JWT, extracts userId, role, schoolId
RolesGuard	Checks if user role has permission for the module
SchoolIdGuard	Ensures schoolId in JWT matches requested resource

Environment Variables

See Configuration for the full list of environment variables required by the API.