Subjects Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The subjects table: the school-wide catalogue of what is taught, independent of any class.
• The class_subjects table: one class teaching one subject, with its own teacher and its own effective mark scheme.
• Admin CRUD on both tables (SubjectsController, ClassSubjectsController), gated by the Subjects and ClassSubjects permission modules.
• Two audience-scoped consumer reads that sit in a different NestJS module (mobile/student, mobile/teacher) but consume this module's DTOs and tables directly: a pupil's and a teacher's own "my subjects" list.
• The Redis cache for the subject catalogue (list, options, single-row reads).

Does Not Own

• classes, grades, sections, rooms — owned by the rest of AcademicStructureModule; this surface only reads them, to join and to validate a classId at assignment time.
• staff, designations, users — owned by PeopleModule; read-only, to validate and render a teacherId.
• academic_sessions — owned by the school-profile/session module; read-only, to resolve "the current session" for the two consumer reads.
• Row-level access scoping logic itself — PeopleAccessService in PeopleModule owns the scopeFor/applyScope mechanism this module calls.
• Portal-audience assertion logic — portal-audience.ts in modules/mobile/shared owns assertPortalAudience/assertTeacherStaffRow.
• Permission catalogue definition — packages/db/src/authorization/permission-catalog.ts is the single source for module/action names; this surface only consumes Subjects_*/ClassSubjects_* codes from it.

Source of Truth

3. Module Composition

AcademicStructureModule imports EnrollmentsCoreModule, PeopleModule, RoleModule and ActivityModule. The subject surfaces add no new import: ClassSubjectsReadService needs PeopleAccessService and PeoplePermissionsService, both of which already arrive through the existing PeopleModule import — so the subject controllers introduce no new edge to the module dependency graph.

4. File and Directory Map

apps/api/src/modules/academic-structure/
  academic-structure.module.ts
  subjects/
    subjects.controller.ts
    subjects-read.service.ts
    subjects-write.service.ts
  class-subjects/
    class-subjects.controller.ts
    class-subjects-read.service.ts
    class-subjects-write.service.ts
  dto/
    subject.dto.ts
    class-subject.dto.ts
    index.ts
  __tests__/
    subjects-read.service.integration.spec.ts
    subjects-write.service.integration.spec.ts
    class-subjects-read.service.integration.spec.ts
    class-subjects-write.service.integration.spec.ts
    class-subjects-authorization.integration.spec.ts

apps/api/src/modules/mobile/
  student/
    student-portal.controller.ts   (StudentSubjectsPortalController)
    student-portal.service.ts      (listMySubjects)
    student-portal.module.ts
  teacher/
    teacher-portal.controller.ts   (TeacherSubjectsPortalController)
    teacher-portal.service.ts      (listMySubjects)
    teacher-portal.module.ts
  shared/
    portal-audience.ts
  __tests__/
    portal-subjects.integration.spec.ts

packages/db/src/schema/school/subjects.ts
packages/db/src/migrations/0017_subject_module.sql
packages/db/src/migrations/0018_subject_permission_grants.sql

5. Data Model

5.1 Schema Source

packages/db/src/schema/school/subjects.ts
  subjectTypeEnum          -- "compulsory" | "optional"
  subjects                 -- the catalogue
  classSubjects             -- one class teaching one subject
  subjectsRelations
  classSubjectsRelations

5.2 Tables and Collections

subjects

Money/marks units: plain integers, no currency, no fractional marks. Timezone: updated_at/created_at are timestamptz, stored and compared in UTC. Soft delete: none — this table hard-deletes.

class_subjects

No JSON columns on either table. No denormalized copy of academic_session_id on class_subjects — deliberately: the table's one invariant ("one assignment per class+subject") does not span the session join the way student_class_enrollments does, so there is nothing a copy would need to keep true.

Index rationale

5.3 Relationship Diagram

6. Services and Responsibilities

6.1 SubjectsReadService

Input normalization: search terms are escaped with escapeLikePattern before being wrapped in %...% for ILIKE, so a literal % or _ in a subject name cannot turn a filter into an unintended wildcard. Validation order: none at this layer — validation is the DTO pipe's job; this service only reads. Transaction boundaries: none — every read here is a single statement or a single correlated query; loadDto accepts an executor so a caller inside a transaction can pass its tx instead of racing a second pooled connection against an uncommitted write. Idempotency: reads are naturally idempotent. Response mapping: toDto is field-by-field, never a row spread — an added column on subjects cannot leak into the response by accident. Fail-open/fail-closed: cache failures fail OPEN to the database (a miss, never an error); a genuinely missing row fails CLOSED with 404. Logger usage: none directly — Redis failures are logged inside RedisCacheService itself.

6.2 SubjectsWriteService

Input normalization: name is trimmed server-side on both create and update, independent of the DTO's own no-surrounding-whitespace validator (belt and braces — the validator refuses a padded value before it reaches the service at all, but the service still trims defensively). Validation order: "not found" is checked first (no constraint could turn an unknown publicId into anything better than a zero-row update); "already taken" is left to the database's partial unique indexes and translated after the fact, which is what makes that check atomic under a race; reactivation collisions are checked application-side, pre-write, because the partial indexes cannot see them yet at check time. Transaction boundaries: create and update each run inside this.db.transaction(...); remove does not need one — its own pre-check and delete are each single statements, and a TOCTOU race is still caught by the foreign key at delete time. Idempotency: none claimed — a second identical create produces a second row (subject to the uniqueness constraint) or a conflict. Retry behavior: none built in; a 409 is the caller's signal to reload and retry with a fresh version. Response mapping: after every write, the service re-reads the row through SubjectsReadService.loadDto, passing its own transaction handle so the response reflects the just-written, not-yet-committed state. Fail-open/fail-closed: writes fail closed — any constraint violation or business-rule failure aborts the transaction. Logger usage: none directly.

6.3 ClassSubjectsReadService

Input normalization: none beyond what the DTO pipe already did. Validation order: assertPaginated runs FIRST in both list methods, before any query is built — a pagination-disabled request never reaches the database. Transaction boundaries: none of its own; loadDto accepts an executor so the write service can call it from inside an open transaction. Idempotency: reads are naturally idempotent. Retry behavior: none. Response mapping: toDto/toClassDto are both field-by-field; teacher maps to null when teacherId is absent, never an empty object. Fail-open/fail-closed: row scope fails CLOSED — default and every unhandled scopeKind in PeopleAccessService.scopeFor resolve to selfOnlyScope, which for classSubjects is sql\false`(no rows), notall`. Logger usage: none.

6.4 ClassSubjectsWriteService

Input normalization: Object.hasOwn is used throughout assign/update to distinguish an ABSENT field (keep existing value) from an explicit null (clear the teacher) — a plain dto.teacherId !== undefined check cannot make that distinction because undefined covers both "not sent" and, in principle, "sent as null and then coerced", so the code deliberately uses the stricter own-property check. Validation order in assign, ten numbered steps: (1) resolve the subject, refuse if missing/inactive; (2-4) resolve every class in one query, collect not-found/inactive/duplicate-in-batch; (5) resolve every teacher in one query, collect not-found/not-teaching; (5 cont./7) default absent type/marks from the subject, validate the cross-column marks bound per item; (6) load label collisions and existing rows for version/suspension decisions; (8) if ANY item failed, throw with the full error list — nothing written; (9) upsert every surviving item; (10) invalidate the cache after commit. Transaction boundaries: assign and update both run inside this.db.transaction(...); remove does not need one. Idempotency: re-sending the identical batch body is idempotent (every field already matches, the SET clause becomes a no-op that still fires the version trigger); re-sending a SUBSET is a partial edit by design, not an idempotency violation. Retry behavior: none built in beyond the caller reloading and resubmitting with fresh versions. Response mapping: assign returns { assigned: ClassSubjectDto[], skippedSuspended: string[] }; every other method returns a single ClassSubjectDto or nothing (remove). Fail-open/fail-closed: validation collects rather than short-circuits inside assign, but the WRITE itself is fail-closed — any single collected error blocks the entire batch. Logger usage: none directly.

7. Runtime Flows

7.1 Assign a subject to classes (the module's most complex flow)

7.2 Update a subject (optimistic concurrency, reactivation)

7.3 Pupil reads their own subjects

Success path, validation failures, permission failures, missing entity, duplicate request, cache miss/hit, async enqueue, race/concurrency, guest vs logged-in — covered per flow:

• Success path: as diagrammed above for each of the three write/read families.
• Validation failures: caught by the global ValidationPipe before any handler runs — malformed publicId (not a UUID for class-subjects/:id), out-of-range marks, bad enum values.
• Permission failures: RoleGuard refuses before the controller method body runs, for every admin route; the two consumer routes are refused inside the service by assertPortalAudience/assertTeacherStaffRow instead, since they carry no @Permissions().
• Missing entity: every read/write that resolves a publicId or id throws the entity's own _NOT_FOUND code first.
• Duplicate request: the assignment upsert is the only place a duplicate submission is meaningfully idempotent — see 6.4.
• Cache hit/miss: only SubjectsReadService.findAll is cached; every other read in this module is always live.
• Async enqueue: not applicable — no queue exists on this module.
• Race/concurrency: version columns plus the identity unique index are the two mechanisms; see 12.3 in the feature doc.
• Guest vs logged-in: no guest branch exists anywhere in this module; the global JwtAuthGuard refuses every unauthenticated request before any handler runs.

8. Caching

findOptions and findOne/loadDto are deliberately NOT cached — findOptions is a bounded scan of a reference-sized table, cheap enough on its own; single-row reads are called from inside the write path's own transaction and would need to be invalidated by exactly the same writes anyway.

Deterministic segment order: CacheKeyUtil.build takes an ORDERED tuple list, so the same logical query always produces the same key string — q, type, active, pagination, page, size, in that fixed order. Cache hit behavior: returned as-is, no re-validation against the database. Cache miss behavior: full query runs, result is written back with a 300s TTL. Serialization shape: JSON.stringify/JSON.parse inside RedisCacheService.getSoft/setSoft — Date fields round-trip as ISO strings, which the response DTO's @ApiProperty() readonly createdAt!: Date typing does not itself enforce at runtime. Invalidation on mutations: EVERY writer on either table calls delPatternSoft("academic-structure:subjects:*") — SubjectsWriteService.create/update/remove AND all three ClassSubjectsWriteService methods, because SubjectDto.classCount is a live count over class_subjects and every one of those writers moves it. Failure handling: fail-soft in both directions — a cache-read failure is treated as a miss (never surfaced), a cache-write or invalidation failure is logged as a WARN and otherwise swallowed, so a Redis outage degrades this module to "every read hits Postgres", never to an error.

9. BullMQ, Schedulers, and Async Work

Not applicable. No queue, job, or scheduled task reads or writes subjects or class_subjects.

10. Realtime and Events

Not applicable. Neither table participates in the realtime/outbox event contract (modules/realtime/shared/realtime.contract.ts); the only event that surface currently carries is feedback.submitted, unrelated to this module.

11. Security, Auth, and Abuse Controls

• Guards: JwtAuthGuard (global) and RoleGuard on every admin route in SubjectsController/ClassSubjectsController. The two consumer routes carry JwtAuthGuard + RoleGuard as well, but declare NO @Permissions() — RoleGuard returns true for a handler with no declared permission that sits on the NO_PERMISSION_ADMIN_HANDLERS allowlist, so the actual boundary for those two routes is entirely inside the service.
• Permissions: Subjects_READ/_CREATE/_UPDATE/_DELETE/_RESTORE and ClassSubjects_READ/_CREATE/_UPDATE/_DELETE/_RESTORE — five actions each, generated automatically by buildPermissionCatalog() over PERMISSION_MODULES. _RESTORE on both is unreachable: neither table has a soft-delete column, and no controller declares a restore route.
• Guest identity: none — no route in this module accepts an unauthenticated caller.
• Admin identity: req.user plus activeRole, resolved by JwtAuthGuard/RoleGuard; superadmin bypasses every permission and scope check via actor.activeRole?.isSuperadmin.
• Rate limits: none declared specifically for this module.
• Anti-abuse rules: the 1-100 item cap on AssignSubjectToClassesDto.items (ASSIGNMENT_BATCH_MAX) bounds the size of a single write, matching the admin grid's own page size so the over-size case is unreachable from the panel and needs no dedicated error code — the global pipe's 400 covers it.
• Input normalization: server-side name trimming on create/update; regex validators on name/code mirror the database CHECK constraints in JavaScript escape-sequence spelling (the two are deliberately NOT identical spellings — \s inside a Drizzle sql template literal does not survive, so the constraint uses POSIX character classes while the DTO uses standard JS regex).
• Sensitive data redaction: ClassTeacherDto (embedded in ClassSubjectDto.teacher) carries an employee code and employment status — this is exactly why ClassSubjects_READ is withheld from pupils and guardians, and why the pupil/teacher consumer DTO (MySubjectDto) is written field-by-field rather than reusing or Pick<>-ing the admin shape.
• Audit logs: every mutating admin route is recorded automatically by the global ActivityAuditInterceptor, keyed off the handler's @Permissions() code (Subjects_CREATE → module Subjects, action CREATE). No service in this module calls the audit recorder directly — nothing here needs per-field changes detail beyond what the interceptor already captures.
• Fail-closed behavior: PeopleAccessService.isVisible THROWS for the "classSubjects" entity rather than returning true or falling through a default arm — deliberately, so that if a future single-row check is ever wired up against this entity by mistake, it fails loudly (an unhandled error) instead of silently granting access. The two list reads never call isVisible; they apply scopeFor + applyScope directly to the list query, which is the actual and only boundary for class_subjects reads today.
• The Parent Portal incident and its fix, restated for this module: PeopleAccessService.scopeFor's "role decides scope before permission does" ordering exists specifically because the seeded staff/teacher roles hold BOTH Students_READ (scope all) AND ClassSubjects_READ. Were the ordering reversed, holding the permission would return {kind:"all"} unconditionally, defeating the whole point of scoping. The two consumer "my subjects" routes go further and never touch scopeFor at all — they build their own predicate from assertPortalAudience/assertTeacherStaffRow plus an explicit WHERE, closing the specific hole where a broadly-scoped staff session reading a route literally named /student/subjects would otherwise see every pupil's schedule.

13. Error Handling

14. Observability

15. Testing and Validation

All of the above connect to the real test database via TEST_DATABASE_URL and run the actual Drizzle migrations — no mock of DatabaseModule, Redis, or any @skoolsewa/* package, per this repo's testing rule.

Validation commands:

pnpm --filter @skoolsewa/api test -- academic-structure/__tests__/subjects
pnpm --filter @skoolsewa/api test -- academic-structure/__tests__/class-subjects
pnpm --filter @skoolsewa/api test -- mobile/__tests__/portal-subjects
pnpm --filter @skoolsewa/api test:structure

16. Mandatory Backend Deep-Dive Pack

16.1 Submodule Coverage Matrix

16.2 UML and Architecture Diagram Pack

No BullMQ, no Socket.IO gateway, and no external API call anywhere in this module — the deployment/runtime diagram above is deliberately short.

16.3 Code Flow Narrative

See 7.1 for assign()'s full fifteen-point narrative (entry point through logs/tradeoffs) and 7.2 for update()'s. Both are also documented at length in the source files' own docblocks, which this page's tables draw from directly rather than restating differently.

16.4 Data Layer Deep Dive

Covered in full in 5.2 (field tables, business meaning, nullability, validation source, indexes, constraints, FK delete behavior, versioning, timezone) and the Index rationale table immediately after it. Neither table has JSON columns, money units, soft-delete fields, or seed-data dependencies — both are pure operational tables populated entirely through the API.

16.5 Business Logic and Invariant Catalog

16.6 Tradeoffs, Alternatives, and ADR Notes

16.7 Operational Runbook

16.8 Backend Risk Register

17. Zero-Omission Backend Checklist

• Every file in the module directory is represented or explicitly marked non-runtime.
• Every controller, service, DTO, enum, and schema is documented.
• Every method with business behavior has a code-flow narrative.
• Every table has field-level detail.
• Every index, constraint, relation, and delete behavior has rationale.
• Every lifecycle/status transition has a state diagram and transition table — see the feature doc's Section 7.
• Every read/write/action flow has a sequence diagram.
• Every business invariant is cataloged.
• Every cache key and invalidation path is documented; there is no queue, realtime event, or external call to document.
• Every architectural tradeoff is documented with alternatives and revisit triggers.
• Every operational failure mode has a runbook entry.

18. Backend Completion Checklist

• Module boundaries are documented.
• Every controller, service, DTO, schema file, and cache key is covered.
• Every database table has a field table and relationship diagram.
• Every runtime flow has a diagram and branch notes.
• API, feature/flows docs are linked; no TDD document exists for this module.
• No claim is made without a source file or documented source reference.

See Also

• API doc: /docs/developer/subjects/api
• Features and flows doc: /docs/developer/subjects/feature