Complaints Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The complaint lifecycle from draft through submission, triage, handling, resolution, closure, reopening, rejection, cancellation and archival.
• Every configuration surface the process runs against: categories, templates, priorities, category×priority SLA rule overrides, the singleton general settings, per-kind reminder settings, per-event notification-channel settings, and escalation rules.
• The admin register: list, detail, event timeline, statistics, and the assignee picker.
• The complainant portal at /api/mobile/complaints: filing (with category-specific questions and required fields), draft management, submission, the complainant's own follow-up actions (respond to an information request, confirm a resolution, reopen, cancel), and attachment upload/download scoped to the complainant's own complaints.
• The evidence attachment pipeline shared by both surfaces: multer configuration, magic-byte sniffing, structural scanning, image re-encoding, refusal cleanup, temp-file cleanup, and download.
• The automated sweep: overdue flagging, reminders, escalation, and automatic closure, run every five minutes by one BullMQ worker.
• Anonymity: masking every identifying field on every read path except the complainant's own portal view, and the one audited reveal path.
• The permanent, append-only event history of every complaint.

Does Not Own

• Authentication, session issuance, and role/permission storage — RoleModule, imported by ComplaintsSharedModule and re-exported so every controller's RoleGuard can inject RoleService.
• Notification delivery and template rendering — NotificationModule; this module only decides WHO gets notified and WHICH event key fired, and reads channel/enable settings back from its own complaint_notification_settings table.
• File storage and structural scanning infrastructure — packages/storage and AssignmentFilesModule's scanning services, reused rather than re-implemented (imported by ComplaintAttachmentCoreModule).
• Academic-session, class, grade and section identity — packages/db/src/schema/school/academic-sessions.ts and classes.ts; complaints only snapshot the academic context at filing time via ComplaintPolicyService.academicContext, reusing AttendanceSharedModule's session/date resolution.
• Student, guardian and staff identity — packages/db/src/schema/school/people.ts; complaints reference students.id/staff.id and resolve audience membership through those tables but never writes to them.
• The activity audit log and notification-history screens — activity and notification/admin/history own those tables; this module only tells them which entries must be redacted.

Source of Truth

3. Module Composition

4. File and Directory Map

apps/api/src/modules/complaints/
  complaints.module.ts
  attachments/
    complaint-attachment-core.module.ts
    complaint-attachment-download.service.ts
    complaint-attachment-multer-error.filter.ts
    complaint-attachment.multer.ts
    complaint-attachment-refusal-cleanup.ts
    complaint-attachment-scan.ts
    complaint-attachments.controller.ts
    complaint-attachment.service.ts
    complaint-attachments.module.ts
    complaint-attachment-sniff.ts
    complaint-attachment-surface.ts
    complaint-attachment-temp-file-cleanup.interceptor.ts
    dto/complaint-attachment-upload.dto.ts
  config/
    complaint-categories.controller.ts / .service.ts
    complaint-category-questions.util.ts
    complaint-config.module.ts / complaint-config.util.ts
    complaint-escalation-rules.controller.ts / .service.ts
    complaint-notification-settings.controller.ts / .service.ts
    complaint-priorities.controller.ts / .service.ts
    complaint-settings.controller.ts / .service.ts
    complaint-sla-rules.controller.ts / .service.ts
    complaint-templates.controller.ts / .service.ts
    dto/ (one request + one response DTO per surface, plus complaint-config-common.dto.ts)
  portal/
    complaint-portal.controller.ts / complaint-portal-draft.service.ts
    complaint-portal-actions.controller.ts / .service.ts
    complaint-portal-attachments.controller.ts
    complaint-portal-audience.service.ts
    complaint-portal.module.ts
    complaint-portal-projection.service.ts / .util.ts
    complaint-portal-query.service.ts
    complaint-portal-identity.ts
    complaint-portal.types.ts
    dto/complaint-form-options.dto.ts, complaint-portal-attachment-upload.dto.ts, complaint-portal-request.dto.ts
  register/
    complaint-assignable-users.controller.ts
    complaint-detail.mapper.ts / complaint-detail-query.ts / complaint-list-query.ts
    complaint-list.service.ts / complaint-office-record.service.ts
    complaint-picker.service.ts / complaint-read.service.ts
    complaint-register.module.ts / complaint-result.util.ts
    complaints.controller.ts
    complaint-statistics.controller.ts / .service.ts
    dto/ (assignable-users-query, complaint-statistics-query, list-complaints-query, list-events-query, query-boolean, record-complaint)
  shared/
    complaint-access.service.ts / complaint-draft.service.ts
    complaint-effects.service.ts / complaint-errors.util.ts
    complaint-filing.rules.ts / complaint-history.service.ts
    complaint-masking.util.ts / complaint-notifier.service.ts
    complaint-people.service.ts / complaint-policy.service.ts
    complaints-shared.module.ts / complaint-submission.service.ts
    dto/complaint-response.dto.ts
  workers/
    complaint-queue.processor.ts / complaint.scheduler.ts
    complaint-sweep-anchors.ts / complaint-sweep-shared.ts
    complaint-sweep-auto-close.pass.ts / -escalation.pass.ts / -overdue.pass.ts / -reminders.pass.ts
    complaint-sweep.service.ts / complaint-workers.module.ts
  workflow/
    complaint-actions.controller.ts / complaint-outcome-actions.controller.ts / complaint-bulk.controller.ts
    complaint-bulk.service.ts / complaint-command-base.ts
    complaint-handling.commands.ts / complaint-outcome.commands.ts / complaint-triage.commands.ts
    complaint-workflow.module.ts / complaint-workflow.service.ts
    dto/complaint-action.dto.ts, complaint-bulk.dto.ts
  __tests__/ (8 integration specs + fixtures + test-support)
apps/api/src/utils/complaints/
  complaint-lifecycle.util.ts (+ .spec.ts)
  complaint-sla.util.ts (+ .spec.ts)
  complaint-text.util.ts (+ .spec.ts)

For the highest-traffic files:

5. Data Model

5.1 Schema Source

packages/db/src/schema/school/complaints.ts   -- all 12 tables, all enums
packages/db/src/migrations/0039_complaints.sql        -- table DDL
packages/db/src/migrations/0040_complaints_integrity.sql -- triggers, deferred constraints, seed data

5.2 Tables and Collections

complaint_priority_settings

complaint_categories

complaint_sla_rules

complaint_templates

complaint_settings (singleton, id=1)

complaint_reminder_settings

complaint_notification_settings

complaint_escalation_rules

complaints (aggregate root)

Indexes: partial complaints_status_idx (status, last_activity_at desc) where not archived; partial complaints_assignee_idx; complaints_submitter_idx; partial complaints_due_open_idx for the 5 open statuses; complaints_category_idx; partial complaints_related_student_idx; complaints_session_idx; partial complaints_duplicate_of_idx; two gin_trgm_ops indexes on title/description for search.

complaint_assignments (append history)

complaint_info_requests

complaint_resolutions

complaint_events (append-only permanent history)

Migration 0040's complaint_events_append_only trigger refuses every UPDATE and DELETE on this table.

complaint_attachments

complaint_automation_log

5.3 Relationship Diagram

6. Services and Responsibilities

6.1 ComplaintAccessService (shared/complaint-access.service.ts)

Visibility rule: superadmin OR (NOT submitter AND NOT subject AND (Complaints_READ OR (ComplaintAssignments_READ AND current assignee))), evaluated against the caller's ACTIVE role only. An office record with nobody named (submitter_kind='admin' and recorded_by_user_id = submitter_user_id) has no complainant, so its recorder does not count as the submitter and reads it like any other handler; decide and listVisibilityWhere apply the same exception. The lock is FOR NO KEY UPDATE, never plain FOR UPDATE, because history/attachment inserts elsewhere take KEY SHARE on the same row and must not queue behind an unrelated lock.

6.2 Complaint lifecycle commands (workflow/complaint-triage.commands.ts, -handling.commands.ts, -outcome.commands.ts)

respond_to_information_request, confirm_resolution, reopen_by_complainant and the complainant's cancel live in ComplaintPortalActionsService (§7.4), not in these groups.

Every command follows the same order: ComplaintAccessService.resolveVisible with lock: true → canPerform from the lifecycle util (archived/not-archived/invalid-status refusal → COMPLAINT_ARCHIVED/COMPLAINT_NOT_ARCHIVED/COMPLAINT_INVALID_TRANSITION) → expected-version check (COMPLAINT_VERSION_CONFLICT) → input validation → write inside the same transaction as the version bump, the history event, and (where relevant) the child-table write → notification dispatch. ComplaintWorkflowService is the single entry point that ComplaintActionsController, ComplaintOutcomeActionsController and ComplaintBulkService call, so a bulk action can never drift from its single-item sibling. start checks that the caller is the current assignee (403 COMPLAINT_NOT_CURRENT_ASSIGNEE) before the transition check. After commit, buildCommandResult (register/complaint-result.util.ts) rebuilds the detail with a fresh access decision; if that read fails, it logs the failure and returns { complaint: null, eventId } rather than an error, because the write has already committed.

6.3 ComplaintSubmissionService (shared/complaint-submission.service.ts)

finalise does not enforce the daily submission limit or lock/version-check the row — its own doc comment states those are the CALLER's responsibility ("What the CALLER has already decided and this service does not: who the submitter is and in what capacity; that a named related student is one this caller may name; the per-submitter limits; the lock on the row"). The portal enforces the limits in ComplaintPortalDraftService: create takes the per-submitter lock and checks the 20-draft limit, and checks the daily submission limit when submit is true; submit takes the lock and checks the daily limit. The office record path (ComplaintOfficeRecordService) applies neither limit.

6.4 ComplaintPolicyService (shared/complaint-policy.service.ts)

6.5 ComplaintEffectsService (shared/complaint-effects.service.ts)

6.6 ComplaintHistoryService (shared/complaint-history.service.ts)

6.7 ComplaintNotifierService (shared/complaint-notifier.service.ts)

6.8 ComplaintPeopleService (shared/complaint-people.service.ts)

6.9 ComplaintDraftService (shared/complaint-draft.service.ts) and ComplaintPortalDraftService (portal/complaint-portal-draft.service.ts)

Draft creation, update and discard. A draft consumes no complaint_reference_seq value and writes no complaint_events row, which is what lets discard_draft remove it cleanly (its attachments cascade with it). submissionId is the idempotency key: a second POST with the same (submitterUserId, submissionId) pair hits the partial unique index and is treated as a resend of the same draft rather than a duplicate. The portal checks for a replay before any limit: ComplaintPortalDraftService.create takes the per-submitter lock, then findReplay returns an existing complaint with that submissionId unchanged, and only a new draft goes on to the 20-draft and daily limits.

7. Runtime Flows

7.1 Complainant files and submits a complaint

7.2 Handler acknowledges, assigns, investigates, resolves, closes

7.3 Waiting for information (SLA pause) and resume

7.4 Reopen, reject, duplicate, cancel

7.5 Identity reveal

7.6 Attachment upload (shared pipeline, surface-specific placement)

7.7 The automated sweep (every 5 minutes)

8. Caching

No other Redis caching exists in this module. Configuration reads (complaint_settings, priorities, reminder/notification settings) go straight to Postgres on every call — these are small, infrequently-read rows and the module does not warrant a cache-invalidation surface for them (see §16.6).

9. BullMQ, Schedulers, and Async Work

The 20 notification event keys (complaint_notification_settings): submitted_complainant, submitted_triage, acknowledged_complainant, assigned_assignee, assigned_complainant, reassigned_previous_assignee, information_requested_complainant, information_provided_assignee, response_added_complainant, investigation_update_complainant, overdue_assignee, escalated_recipients, resolved_complainant, closed_complainant, reopened_handlers, rejected_complainant, cancelled_handlers, cancelled_complainant, reminder_staff, reminder_complainant. Each row's channels (subset of in_app/push/email/sms) and isEnabled gate ComplaintNotifierService.notify; apps/api/src/modules/notification/templates/complaint-templates.ts supplies the rendering, and packages/db/src/notification/notification-contract.ts types the payload shape per key.

10. Realtime and Events

This module does not participate in the realtime/SSE transport (modules/realtime). The complaint's own event stream (complaint_events) is a pull surface — GET /complaints/:id/events — not pushed.

11. Security, Auth, and Abuse Controls

• Guards: every controller sits behind the global JwtAuthGuard and RoleGuard. Most routes declare @Permissions(...); four handlers are permission-less by design and resolve visibility themselves inside the handler, each requiring an entry in both NO_PERMISSION_ADMIN_HANDLERS (role.guard.ts) and its CI mirror (route-permissions.spec.ts):
  • ComplaintsController.findOne — visibility from ComplaintAccessService (Complaints_READ OR current-assignee ComplaintAssignments_READ), excluding the complainant and the subject; the recorder of an office record with nobody named is not its complainant.
  • ComplaintsController.listEvents — same visibility, further filtered per-event by ComplaintHistory_READ/ComplaintInternalNotes_READ.
  • ComplaintAttachmentsController.download — declares no @Permissions(); the source comment says not to add one, because a declared permission would override the allowlist and refuse every assignee without it. ComplaintAttachmentDownloadService.downloadForAdmin resolves the owning complaint through ComplaintAccessService.resolveVisible (Complaints_READ, or ComplaintAssignments_READ as the current assignee; never the submitter or the subject; a missing active role is 403 AUTH_ACTIVE_ROLE_REQUIRED). The attachment must belong to that complaint, and an internal attachment also needs ComplaintInternalNotes_READ; otherwise 404 COMPLAINT_ATTACHMENT_NOT_FOUND. Upload stays gated by ComplaintAttachments_CREATE.
  • ComplaintAssignableUsersController.list — requires ANY of ComplaintAssignments_CREATE, ComplaintAssignments_UPDATE, ComplaintEscalation_UPDATE, ComplaintSettings_UPDATE; returns only {userId, name, designation}, not scoped to any one complaint's submitter.
• Permission modules: Complaints (the register, recording, manual due date, archive), MyComplaints (the complainant's own surface — every portal route), ComplaintAssignments, ComplaintTriage, ComplaintPriorityChange, ComplaintCategoryChange, ComplaintResponses, ComplaintInternalNotes, ComplaintInformationRequests, ComplaintAttachments, ComplaintResolution, ComplaintClosure, ComplaintReopen, ComplaintRejection, ComplaintCancellation, ComplaintEscalation, ComplaintHistory, ComplaintIdentity, ComplaintStatistics, ComplaintCategories, ComplaintTemplates, ComplaintPriorities (also gates SLA rules), ComplaintSettings (also gates escalation rules), ComplaintNotificationSettings, ComplaintView (the panel hub screen, zero API routes), ComplaintAudit.
• Superadmin-only modules: ComplaintIdentity and ComplaintAudit are in SUPERADMIN_ONLY_MODULES — a disclosure about a child or colleague cannot be taken back, so neither is part of the automatic admin grant; a school must grant either down to a named role explicitly.
• Portal audience: ComplaintPortalAudienceService.resolve derives the filer's kind (student/guardian/teacher/staff/admin) from activeRole.scopeKind plus a live staff row lookup, following the repo-wide portal rule — every lookup here is identity-layer only (deleted_at filter alone), because a failure here is a 404 against the caller's own audience.
• Row-scope authorization on the register: ComplaintAccessService.listVisibilityWhere builds the WHERE predicate directly — never through PeopleAccessService.scopeFor, whose {kind:"all"} would hand the entire register to any Students_READ holder (the repo-wide portal rule's warning applies verbatim here).
• Anonymity: shared/complaint-masking.util.ts masks submitterView, actorView, attachmentNameView and contactView unconditionally on every admin-surface read, including for ComplaintIdentity_READ holders. The only bypass is the audited revealIdentity action.
• Rate limits: complaint_settings.dailySubmissionLimit (default 10, school-local day via ComplaintPolicyService.schoolToday) is the module's own abuse control on submission volume, enforced by ComplaintDraftService.assertDailySubmissionLimit under a per-submitter lock when the portal submits; a submitter may also hold at most 20 open drafts (COMPLAINT_MAX_OPEN_DRAFTS). The office record path applies neither limit.
• Input normalisation: complaint-text.util.ts removes the invisible set (zero-width and bidirectional controls, the BOM, the soft hyphen, variation selectors U+FE00-U+FE0F, Hangul and other fillers, and the tag block U+E0000-U+E007F) and C0 controls other than tab, LF and CR from every complainant-supplied text field, including free-text answers, and from attachment file names. A bidirectional override can make photo<RLO>fdp.exe display as photoexe.pdf; tag characters can hide text a handler never sees.
• Anonymous attachments: a complainant-capacity upload on an anonymous complaint accepts only jpg, jpeg, png, webp and txt (attachments/complaint-attachment-anonymity.ts). Document formats carry the author's name in their own properties even when the text never names them; images are re-encoded, which drops their metadata, and plain text has none. The check runs at upload (resolvePortalAttachmentPlacement, on the locked row), at submit, and on a draft save as anonymous (assertNoAnonymousUnsafeAttachments), answering 422 COMPLAINT_ATTACHMENT_ANONYMOUS_TYPE_REFUSED. Files a handler attaches are not affected.
• Upload paths and logs: multer writes each upload to uploads/complaint-attachment/<uuid>/ with a fresh uuid per upload and a uuid file name, so the path identifies no one, and refuses a destination that resolves outside the upload root. Storage keys are never logged beside a complaint id. The allowlist includes application/msword and application/vnd.ms-excel for .doc and .xls.
• Audit trail closures (all outside this module's own files, closing anonymity leaks in shared infrastructure):
  • activity-audit.interceptor.ts:85-86 — isComplaintAuditModule(module) redacts actor.endpoint via redactEndpoint before the activity log records it.
  • activity.service.ts:39-93 — activityModuleFilter returns an empty result set for any complaint module requested by a caller who is not superadmin and does not hold ComplaintAudit_READ.
  • notification-history.service.ts — unless the caller is superadmin or holds ComplaintAudit_READ, events of category complaint do not exist on the notification-history screen: the list leaves them out and the detail answers the same 404 as an unknown id. A complaint notification's audience is the complainant, and its title, reference and link reveal that a complaint exists, including to the staff member it is about. Holding ComplaintAudit_READ is therefore equivalent to identity access.
  • upload.service.ts:69-71 — an Upload_READ holder cannot browse complaint files through the generic upload surface; only the complaint's own visibility and attachment-visibility checks gate a complaint file.

13. Error Handling

Every code comes from apps/api/src/common/types/error-codes.ts. Database refusals (a CHECK, a unique index, a trigger raising SQLSTATE 23514 with a constraint name) pass through translateComplaintError in shared/complaint-errors.util.ts, which maps the known constraint names to the codes below and rethrows anything already an HTTP exception unchanged.

14. Observability

15. Testing and Validation

Validation commands: pnpm --filter @skoolsewa/api test, pnpm --filter @skoolsewa/api test:structure, pnpm rules. All specs under __tests__/ connect to the real TEST_DATABASE_URL database — no mocked schema, Redis, or queue.

16. Mandatory Backend Deep-Dive Pack

16.1 Submodule Coverage Matrix

16.2 UML and Architecture Diagram Pack

16.3 Code Flow Narrative

ComplaintSubmissionService.submitDraft (§7.1):

1. Entry: ComplaintPortalDraftService.submit (POST /:id/submit) or .create with submit: true; the office path reaches the same finalise through recordSubmitted.
2. Command shape: complaint id, actor, optional expected-version.
3. Auth: the actor must be the draft's own submitter (portal) or hold Complaints_CREATE (office recording).
4. Normalisation: title/description/location run through complaint-text.util.ts at draft-write time, not here.
5. Validation order, portal submit: own row locked → version → audience resolved → named student re-authorised against the current audience → audience kind must equal the draft's (COMPLAINT_SUBMITTER_KIND_CHANGED) → per-submitter lock → daily limit. Then finalise: category and template usable → text normalised → anonymity rules, including no complainant-uploaded file outside jpg, jpeg, png, webp, txt (COMPLAINT_ATTACHMENT_ANONYMOUS_TYPE_REFUSED) → incident date → template-required fields → answers → related people → attachment-required → guarded update (COMPLAINT_NOT_DRAFT).
6. Reads: category, template, priority settings, applicable SLA rule.
7. Business decision: resolveTargets (precedence template → SLA rule → category → priority) then computeAckDueAt/computeDueAt.
8. Writes: nextval(complaint_reference_seq) (the complaints_assign_reference trigger then issues the opaque reference), status='submitted', submittedAt, ackDueAt, dueAt, dueSource.
9. Transaction: one transaction spans the sequence allocation, the row update, and the history event.
10. Cache: none.
11. Notifications: triage (or the alert variant if the category's priority sets alertOnSubmit), and the complainant if submitted_complainant is enabled.
12. Response mapping: ComplaintReadService's shared detail shape, through submitterView/actorView masking.
13. Errors: see §13's submission-related rows.
14. Logs/audit: complaint_events row (submitted); ActivityAuditInterceptor records the mutating request with redactEndpoint.
15. Tradeoff: allocating the reference at submission rather than draft creation means a draft never carries one. A rolled-back submit leaves a gap in the internal sequence, which nobody outside the database can see, because the public reference is random.

ComplaintTriageCommands.assign (§7.2):

1. Entry: ComplaintActionsController.assign (ComplaintAssignments_CREATE) or ComplaintWorkflowService.assign from bulk.
2. Command shape: complaint id, target assigneeUserId, optional reason, expected version.
3. Auth: permission plus ComplaintAccessService.resolveVisible(lock: true).
4. Validation order: canPerform("assign", status, archived) → version check → no active assignment → isEligibleAssignee.
5. Reads: current active assignment (if any), target user's eligibility.
6. Business decision: nextStatus("assign", from) → "assigned".
7. Writes: sets acknowledgedAt and appends acknowledged when the complaint was never acknowledged, inserts the new active complaint_assignments row, updates complaints.assignedToUserId/assignedAt/status/version.
8. Transaction: single transaction; the deferred constraint trigger validates assigned_to_user_id matches the sole active assignment at commit.
9. Cache: none.
10. Notifications: assigned_assignee to the new assignee, assigned_complainant if enabled.
11. Response: shared detail shape.
12. Errors: COMPLAINT_ASSIGNEE_INELIGIBLE, COMPLAINT_ALREADY_ASSIGNED, COMPLAINT_VERSION_CONFLICT, COMPLAINT_INVALID_TRANSITION.
13. Logs/audit: complaint_events (assigned), activity log.
14. Tradeoff: the assignment table is append-only history rather than a mutable "current assignee" column, so a complaint's whole handling chain survives reassignment — the parent's assigned_to_user_id is a denormalised, trigger-verified pointer to it for query convenience.

Sweep escalation pass (runEscalationPass, §7.7):

1. Entry: ComplaintSweepService.run, third of four passes, with its own deadline share and its own try/catch, so a failure in another pass does not stop it.
2. Candidate source: runSweepPass's keyset page over open complaints matching an active escalation rule's trigger and (category/priority filters).
3. Auth: none — system actor.
4. Per-candidate transaction: SELECT ... FOR NO KEY UPDATE SKIP LOCKED on the one complaint row.
5. Re-check under lock: the anchor (from complaint-sweep-anchors.ts) plus afterMinutes must still be past now — a concurrent state change (e.g. acknowledgement) since the page was fetched must not fire a stale escalation.
6. Claim: tryClaimFiring with the rule's key, the complaint's current SLA cycle, and a sequence number for the escalation level.
7. Writes (only if claimed): complaints.escalationLevel += 1, lastEscalatedAt, version += 1 and lastActivityAt, so a client caching by version sees the new level.
8. History: escalated event, system actor.
9. Notifications: ComplaintNotifierService.escalationRecipients — assignee's manager, triage, and the rule's explicit list.
10. Failure: caught per-candidate, logged, loop continues — one broken escalation rule does not stop the pass for every other complaint.
11. Tradeoff: escalation level has no ceiling in the schema (only >= 0); an unresolved complaint under a short afterMinutes and many active rules can escalate repeatedly — accepted, since suppressing repeats is a rule-authoring concern (isActive), not a data-integrity one.

16.4 Data Layer Deep Dive

Full field tables are in §5.2. Index rationale:

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, provider, processor, scheduler, helper, mapper, DTO, enum, and schema is documented.
• Every method with business behavior has a code-flow narrative (representative methods per stage — submission, assignment, escalation — narrated in full per §16.3; the remaining commands follow the same order documented in §6.2).
• Every table/collection/cache object/job payload has field-level detail.
• Every index, constraint, relation, and delete behavior has rationale.
• Every lifecycle/status transition has a state diagram and transition table.
• Every read/write/action/job flow has sequence and activity diagrams.
• Every business invariant is cataloged.
• Every cache key, invalidation path, queue job, realtime event, and external call is documented.
• 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, job, cache key, and event is covered.
• Every database table/collection has a field table and relationship diagram.
• Every runtime flow has a diagram and branch notes.
• API, feature/flows, and TDD docs are linked.
• No claim is made without a source file or documented source reference.

See Also

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