ID Cards Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The school's ID-card templates: an mm-based JSON design (front/back, elements, dynamic field keys), a draft/active/inactive/archived lifecycle, immutable published versions, per-scope assignment rules, and one default template per card type.
• Card-image assets (logos, seals, signatures) uploaded as the private ID_CARD_ASSET upload type, sniffed by magic bytes, served only through the authenticated relay.
• Candidate selection and readiness review for generation — which students/staff are eligible and what would block generation before it runs.
• Card generation itself: a single synchronous card, or a bulk request processed asynchronously through the outbox → BullMQ → a lease-fenced worker.
• The full card lifecycle: generated → printed → active → expired/lost/stolen/damaged/replaced/cancelled/deactivated, including incidents, replacements, print marking, downloads, and an append-only per-card event history.
• QR/token verification: an authenticated staff scan (IdCardVerify_READ) and a public, unauthenticated verification page reachable from a printed card's QR code.
• Module settings: numbering (prefix + sequence + padding), validity defaults, generation requirements, printing defaults, notification switches, and a separately-gated public-verification configuration.
• Two scheduled sweeps: a 5-minute recovery sweep for generation jobs whose worker died mid-lease, and an hourly lifecycle sweep (expiry, expiring-soon notices, leave-triggered deactivation, event-history pruning).
• Six notification kinds delivered through the shared NotificationService.

Does Not Own

• Student, staff, and guardian records (people/ module) — this module reads them and never writes them, except through row-scoped, permission-gated queries.
• Classes, sections, academic sessions (school/ schema, academic-sessions) — read-only references for placement and validity.
• File storage bytes (@skoolsewa/storage) — the module owns id_card_assets metadata and calls the storage manager directly.
• The outbox and BullMQ infrastructure (OutboxService, @skoolsewa/jobs) — the module is a producer/consumer, not the owner.
• Notification delivery mechanics (channel senders) — NotificationService owns that; this module supplies templates, recipients, and event triggers.
• Authentication and permission evaluation (JwtAuthGuard, RoleGuard) — the module supplies @Permissions() codes and, for scan/verify, its own disclosure rules.
• Timezone/"today" computation — SchoolClockService supplies the school's current date; the module's pure rule functions never read a clock themselves.

Source of Truth

3. Module Composition

There is no aggregate IdCardsModule. Eight admin-facing leaf modules and one worker module are composed directly by app.module.ts, mirroring the rule that ADMIN_MODULES must name a module that declares its own controllers.

4. File and Directory Map

apps/api/src/modules/id-cards/
  templates/
    admin/           id-card-templates.controller.ts, id-card-template-assignments.controller.ts
    core/             templates/assignments/lifecycle/query/mapper services, dto/
    id-card-templates-admin.module.ts
    id-card-template-assignments-admin.module.ts
  assets/
    admin/            id-card-assets.controller.ts
    core/             id-card-assets.service.ts, dto/
    id-card-assets-admin.module.ts
  settings/
    admin/            id-card-settings.controller.ts
    core/             id-card-settings.service.ts, dto/
    id-card-settings-admin.module.ts
  generation/
    admin/            id-card-generation.controller.ts, id-card-generation-jobs.controller.ts
    core/             candidates/generate/job-mapper/jobs-read/jobs/people-picker/preview services, dto/
    id-card-generation-admin.module.ts
  cards/
    admin/            id-cards.controller.ts, id-card-actions.controller.ts
    core/             dashboard/detail/issue-action/lifecycle-action/list/mapper/print-action/render-action/
                      replacement-action/replacements-read services, dto/
    id-cards-admin.module.ts
  verification/
    admin/            id-card-scan.controller.ts
    public/           id-card-verification-public.controller.ts
    core/             id-card-scan.service.ts, id-card-verification-public.service.ts, dto/
    id-card-scan-admin.module.ts
    id-card-verification-public.module.ts
  shared/
    id-card-card-sources.types.ts, id-card-factory.service.ts, id-card-left-holder.util.ts,
    id-card-notifier.service.ts, id-card-person-reader.service.ts, id-card-readiness.service.ts,
    id-card-render.service.ts, id-card-scope.service.ts, id-card-settings-reader.service.ts,
    id-card-snapshot.ts, id-card-template-resolver.service.ts, id-card-transition.service.ts,
    id-cards-shared.module.ts
  workers/
    id-card-generation-runner.service.ts, id-card-lifecycle-sweep.service.ts,
    id-card-recovery-sweep.service.ts, id-cards-queue.processor.ts, id-cards.scheduler.ts,
    id-cards-worker.module.ts

apps/api/src/utils/id-cards/
  id-card-design.ts        (1178 lines — the mm-based design schema and its validator)
  id-card-rules.util.ts    (271 lines — verdict, validity windows, card-number formatting)

Key Files

5. Data Model

5.1 Schema Source

packages/db/src/schema/school/id-cards.ts

One file, 8 enums and 9 tables. Migrations: 0033_id_card_module.sql (tables, indexes), 0034_id_card_constraints_and_seeds.sql (the card-number sequence, bump_row_version triggers, the seeded settings row, and the two append-only guard triggers).

5.2 Enums

5.3 Tables

id_card_settings

Singleton row (id = 1, CHECK id = 1), seeded by migration 0034.

id_card_assets

A design references an asset by public_id, never by storage key — the storage key never reaches the wire.

id_card_templates

Key checks: draft status implies no published version; active/inactive require one; a session-bound template is never a default.

id_card_template_versions (append-only)

Append-only guard: a BEFORE UPDATE OR DELETE trigger raises id_card_template_versions is append-only on any write, with one exception — the published_by_user_id SET NULL cascade fired at pg_trigger_depth() > 1 when a user row is deleted. A direct UPDATE at depth 1 is refused even if it would set the same column to the same value. A version is what a card was generated from and must render the same card for as long as the card exists.

id_card_template_assignments

"Grade 1-5 use the junior card." One row per exact scope.

id_card_template_assignments_scope_unique is a unique index over (card_type, coalesce(session,0), coalesce(grade,0), coalesce(section,0), coalesce(department,0), coalesce(designation,0)) — coalesce lets "any session" (NULL) collide correctly with another "any session" row rather than being distinct every time (Postgres treats NULL <> NULL in a unique index). id_card_template_assignments_section_needs_grade refuses a section-only scope, since sections are shared across grades.

id_card_generation_jobs

A bulk generation request, processed under a lease.

Indexes: id_card_generation_jobs_open_idx (partial, on status where open), id_card_generation_jobs_requester_idx (requested_by_user_id, created_at — backs the row-scoped list).

id_cards

The duplicate guard (why it is a partial unique index, not a service check): id_cards_one_active_student/_staff allows at most one active card per person; id_cards_one_pending_student/_staff allows at most one generated/printed card per person; id_cards_one_live_replacement allows at most one non-terminal replacement chained off a given predecessor. Bulk generation, single generation, and replacement can all attempt to create a card for the same person concurrently, and only the index observes every writer atomically. Issuing a successor while the person still holds an active card flips the old card out of active FIRST, in the same transaction, because a unique index is not deferrable.

Other indexes: id_cards_status_type_idx, id_cards_placement_idx (session/grade/section), id_cards_template_version_idx, id_cards_student_history_idx/_staff_history_idx (person + generated_at, for a person's card history), id_cards_active_valid_until_idx (partial, status = 'active' — feeds the expiry sweep), id_cards_person_name_idx (lower(name) text_pattern_ops, for prefix search), id_cards_generation_job_idx, id_cards_replaces_idx.

id_card_events (append-only)

Per-card history: every transition, print, download, and scan.

Append-only guard: BEFORE UPDATE OR DELETE trigger raises id_card_events is append-only, with two exceptions: the actor_user_id SET NULL cascade at pg_trigger_depth() > 1, and a DELETE of verified rows when the transaction has run SET LOCAL id_cards.allow_event_prune = 'on'. SET LOCAL ends with the transaction, so the permission cannot leak onto a pooled connection and outlive the prune that requested it — only the lifecycle sweep's retention prune sets it.

Indexes: id_card_events_card_idx (card_id, created_at), id_card_events_type_idx, id_card_events_actor_card_idx.

id_card_generation_job_items

One row per person in a bulk generation job.

Uniqueness: (job_id, student_id) and (job_id, staff_id), each partial on the respective column being non-null — a person appears at most once per job. id_card_generation_job_items_job_status_idx (job_id, status, id) backs both the caller's row-scoped item list and the worker's next-pending scan.

5.4 Relationship Diagram

6. Services and Responsibilities

6.1 IdCardTemplatesService / IdCardTemplatesLifecycleService / IdCardTemplatesQueryService

Explain: template creation and update validate the design against id-card-design.ts's schema before persisting draft_design; publish is the only path that writes an immutable id_card_template_versions row, and it re-validates the full design (not just the diff) because a draft accumulated edits since the last publish. card_type is fixed at creation because the field catalogue for elements (photo, roll number, guardian name, etc.) is type-specific.

6.2 IdCardGenerateService / IdCardCandidatesService / IdCardPeoplePickerService / IdCardPreviewService

generateCards runs the readiness review (IdCardReadinessService) before writing; a failing readiness check for any selected person aborts that person's row without failing the whole batch when called through the bulk path (see §7.3), but refuses outright for the single-card path.

6.3 IdCardGenerationJobsService / IdCardGenerationJobsReadService

create()'s per-user pg_advisory_xact_lock(hashtext('id_card_jobs:<userId>')) is taken BEFORE the open-job count is read — a second concurrent submit from the SAME user blocks on the lock rather than racing the count, which would otherwise let two submits both read "0 open jobs" and both pass the cap.

Row scoping (in-flight behavior). list(), detail(), items(), cancel(), and retry() are scoped to the caller: a caller sees and acts on only the jobs they requested, unless their people-scope for the job's card_type is unrestricted ({kind:"all"}), in which case they may act on any job. A job outside the caller's scope answers 404, not 403 — an id space over generation jobs must not become an enumeration oracle. items() additionally filters the returned item rows by the caller's own people scope (e.g., a scoped teacher sees only items for students within their own class scope), even when the parent job itself is visible.

cancel() and retry() lock the job row with FOR UPDATE before deciding the transition, so a concurrent cancel-and-retry pair, or the worker racing to claim the job, serializes on that lock rather than on a repeated status predicate. retry() explicitly refuses cancelled and cancelling jobs rather than reporting "nothing to retry" — a cancelled job's items were deliberately skipped, and retrying one is a status error, not an empty-retry no-op.

6.4 IdCardDetailService / IdCardListService / IdCardDashboardService

Guardian disclosure (in-flight behavior). IdCardDetailService.detail() computes canSeeGuardian = isSuperadmin || held.includes("Guardians_READ") and, when false, strips the guardian block from the returned snapshot entirely rather than nulling its fields — a caller without the permission cannot infer even that guardian data exists on the snapshot. IdCardPreviewService's preview-data path applies the same check but resolves guardian.* fields to empty strings instead, because preview renders directly into the design's field placeholders and an omitted key would leave a broken placeholder on screen.

6.5 IdCardIssueActionService / IdCardLifecycleActionService / IdCardPrintActionService / IdCardReplacementActionService

ID_CARD_NOT_YET_VALID (in-flight behavior). issue() refuses to issue a card whose validFrom is after the school's current date (per SchoolClockService) — a card cannot be handed to its holder before its own validity window begins. Thrown from IdCardIssueActionService.

7. Runtime Flows

7.1 Template Design and Publish

7.2 Single Card Generation

Branches: person already holds an active card (ID_CARD_ACTIVE_CARD_EXISTS), a pending card (ID_CARD_PENDING_CARD_EXISTS), readiness fails (ID_CARD_PERSON_NOT_READY), the session has ended for a student card (ID_CARD_SESSION_ENDED), or an administrator-supplied validity window is invalid (ID_CARD_VALIDITY_INVALID).

7.3 Bulk Generation Job

The outbox write and the job/item rows commit in the same transaction as create(), per the repo-wide outbox invariant — a direct queue.add() in the request handler is never used here.

7.4 Recovery and Lifecycle Sweeps

IdCardRecoverySweepService (every 5 minutes) finds jobs whose lease_expires_at has passed while status = 'running', increments recovery_count (capped at 10), and re-enqueues them so a crashed worker's job resumes rather than hanging forever. IdCardLifecycleSweepService (hourly) sets status = 'expired' for active cards past valid_until, sends the "expiring soon" notification once per card (via expiry_notified_at), deactivates cards for people who have left when auto_deactivate_on_leave is enabled, and prunes verified events past scan_event_retention_days under SET LOCAL id_cards.allow_event_prune = 'on'.

7.5 Authenticated Scan and Public Verification

Disclosure rule (in-flight behavior). A token-based scan (IdCardVerify_READ) returns the full card, plus guardian contacts when the caller also holds Guardians_READ. A card-number lookup through the same endpoint returns basic info only — a card number is guessable in a way a 192-bit token is not, so the full-detail path is reserved for a caller who actually scanned the QR. Deactivation on scan/verify (in-flight behavior). Both the authenticated scan and the public verification page return a deactivated verdict when the holder has left the school or been soft-deleted, even before the hourly lifecycle sweep has recorded the deactivation on the card row itself — the check re-reads person status live rather than trusting the card's own stored status.

8. Caching

The module keeps no Redis-backed cache of its own. All reads go directly to PostgreSQL; the only "cache" behavior is the frozen snapshot/verify_url fields on id_cards, which exist precisely so a historical card never re-reads live data.

9. BullMQ, Schedulers, and Async Work

IdCardsQueueProcessor's handler map is a Record<IdCardJob, handler> — a job name with no handler is a compile error, matching the repo-wide rule that a queue dispatcher's handler map must be exhaustive. Concurrency is fixed at 1: generation holds a lease per job and the sweeps are whole-school passes, so nothing here benefits from parallel execution within this worker. Every job failure is recorded through JobFailureRecorderService (the shared dead-letter/failure-queue mechanism).

10. Realtime and Events

None. The ID-cards module emits no realtime/Socket.IO events; the only cross-cutting event surface it uses is the shared notification system (§ below) and the outbox for BullMQ.

11. Security, Auth, and Abuse Controls

• Guards: JwtAuthGuard (global) + RoleGuard on every admin route; @Permissions() codes as listed in the API doc's permission table. IdCardVerificationPublicController carries neither — its two routes are @Public().
• Permissions: 10 IdCard* modules in permission-catalog.ts, none granted to the seeded staff, teacher, student, or guardian roles by default — a card carries a child's photo, date of birth, and guardian contacts, so every reader is an explicit administrative grant. IdCardPublicVerification is additionally listed in the module's own restricted set (superadmin-only), because it controls what the open internet learns about a child.
• Row scoping: every route that returns a person applies the caller's people scope (Students_READ/Staff_READ-derived), so a role holding IdCards_READ alone cannot see anyone until it also holds a people-read code.
• Rate limits: PUBLIC_CARD_VERIFY (60/min per IP, plain ip strategy — deliberately not ip+device, since both signals in that composite are caller-controlled and a scraper rotating either would get a fresh bucket), ID_CARD_SCAN (120/min per account), ID_CARD_JOB_SUBMIT (20/hour per account, bounding concurrent load given a job can carry up to 2000 people).
• Path validation: every :publicId route param across the module's controllers is UUID-validated by the parameter pipe — a malformed value returns 400 before any query runs.
• Sensitive data redaction: verification-token URLs are redacted from error logs (utils/http/redact-url.util.ts), so a stack trace or log line never leaks a live token.
• Response privacy headers: IdCardVerificationPublicController sets Cache-Control: no-store, X-Robots-Tag: noindex, and Referrer-Policy: no-referrer on both its routes — a search engine must never index a child's card, an intermediate cache must never retain one, and a followed link must never carry the token onward in a Referer header.
• Photo/asset access: id_card_assets are private-typed uploads, sniffed by magic bytes at upload time, served only through the authenticated id-card-assets/:publicId/file relay — never a public storage URL.
• Fail-closed decisions: guardian-block omission (not nulling) on detail reads without Guardians_READ; 404 (not 403) for a generation job outside the caller's scope, to avoid an id-enumeration oracle; incident reports are irreversible (a card can never return to active once marked lost/stolen/damaged).

12. Error Handling

The ID_CARD_* and related codes, grouped by area. Every throw carries the code, never a bare HTTP status.

13. Observability

14. Testing and Validation

Validation commands:

find apps packages -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete && pnpm check-types
pnpm test
pnpm --filter @skoolsewa/api test:structure
pnpm check:ci
pnpm turbo run build:docs

See Also

• API doc: /docs/developer/id-cards/api
• Features and flows doc: /docs/developer/id-cards/feature