Discuva — Technical Documentation

Table of Contents

1. System Overview
2. Architecture
3. Data Models
4. Authentication & Authorization
5. Module Reference
6. API Endpoints Quick Reference
7. Check-In Flow
8. Automated Absence Marking
9. Role & Permission Matrix
10. Environment Variables
11. Enum Reference

1. System Overview

A NestJS REST API that manages church membership, service attendance, workforce scheduling, class enrolment, Sunday School sessions, Children Church security check-in, internal announcements, tithe records, internal finance requests, and prayer meeting roster management for a local church.

Core design principles:

• Every church member has one account. Workers are members with an optional WorkerProfile attached.
• A single JWT login endpoint serves all member roles: MEMBER and WORKER. Admin portal access is controlled separately via the admins table.
• There are two distinct frontends: a mobile app for members and workers, and an admin web portal managed via the Admin RBAC system.
• Attendance is tracked per Event, not per slot. One event can have multiple slots but each member gets exactly one attendance record per event.
• Members are PRESENT or ABSENT. Workers can also be LATE (arrived after threshold) or ON_LEAVE (approved leave covering the event date). ON_LEAVE is neutral — it neither contributes to nor breaks the attendance streak.
• Absentees are marked automatically by a background cron job, not by user action.
• Sunday School tracks session-based attendance for permanent class assignments. Both teachers and enrolled students can mark attendance; self-mark requires an open window set by staff.
• Children Church provides a full security check-in/check-out system for 1000+ children, with per-session 6-character pickup codes, multiple guardians per child, automatic age-group assignment by date of birth, and pickup email notifications to guardians.
• Follow-Up tracks first-time visitors and online non-responders. A FollowUpTask is auto-created on every first-timer registration and assigned to a FOLLOW_UP-department worker via round-robin (fewest open tasks wins). After every event, thank-you emails are sent to all attendees and online-confirm requests are sent to absent members if onlineAttendanceEnabled is set. Members who don’t confirm online attendance within ONLINE_CHECKIN_WINDOW_HOURS get a follow-up task.

2. Architecture

src/
├── auth/             Single login, JWT strategy, refresh tokens
├── member/           Universal identity: Member + WorkerProfile
├── event/            Event + ServiceSlot + EventConfig
├── venue/            Named, reusable venue entities (lat/lon)
├── attendance/       Check-in, history, leaderboard, cron job
├── department/       Departments + leads
├── request-leave/    Worker leave requests
├── classes/          ChurchClass + ClassEnrollment
├── announcement/     Announcements with audience targeting
├── birthday/         Birthday greetings, wish wall (BirthdayWish entity)
├── notes/            Pastoral notes (naming, dedication, marriage)
├── dashboard/        Aggregated dashboards per role
├── sunday-school/    Session-based SS classes, members, sessions, attendance
├── children-church/  Age groups, class groups, child profiles, guardians, check-in/out
├── admin/            Admin RBAC: AdminRole + Admin entities, AdminGuard, seed (@Global module)
├── tithe/            Batch tithe upload (Excel), queue-based processing, dispute resolution, member PDF statements
├── finance-request/  Department expense requests lifecycle (submit → approve/reject → proof)
├── follow-up/        First-timer registration, follow-up task management, post-event email jobs, online attendance
├── service-programme/ Service programme authoring, live session control, analytics, PDF reports
├── service-headcount/ Physical attendance headcounts per service slot, trends by period
├── prayer/           Prayer meeting roster: schedule config, day configs, rules, self-selection, auto-assignment, reminders
└── utility/          Email queue, cache, hashing, pagination, email delivery log, Cloudinary file uploads, PDF generation

Stack: NestJS · TypeORM · PostgreSQL · Redis · Bull · ioredis · Argon2 · Passport (JWT + Local) · class-validator · nestjs-schedule · @nestjs/throttler · Handlebars · DOMPurify · ExcelJS · PDFKit · Cloudinary · Nodemailer (Gmail SMTP) · Resend SDK

3. Data Models

Member

The universal identity for every person in the system.

Profile picture: self-service via POST/DELETE members/me/photo (JwtAuthGuard), uploaded to Cloudinary folder profile-pictures (3MB limit, image mimetypes only). Replacing a photo uploads the new one first, saves it, then deletes the previous Cloudinary asset by photoPublicId (fire-and-forget). Admins can also clear a member’s photo via DELETE members/:id/photo (AdminGuard + MEMBERS_WRITE) for moderation. GET /birthday/today’s BirthdayCelebrant shape also carries photoUrl, alongside the existing role/department/pastorType disambiguation for same-named celebrants (see Birthday Module).

WorkerProfile

Created when a member is promoted to WORKER. Never deleted by any revocation path — revokeWorker and demoteTraineeToMember both deactivate the row (status = INACTIVE) rather than removing it, so a member’s worker history (department, profession, completedSOD/completedBibleCollege, isTrainee) survives and is picked back up if they’re later re-promoted.

Deactivation (revokeWorker / demoteTraineeToMember) — shared, non-destructive: both go through a private deactivateWorkerAccess() helper that removes DepartmentLead rows and any Sunday School teacher assignment (no cascade on those FKs), sets workerProfile.status = INACTIVE, and resets member.role = MEMBER. Access is fully revoked immediately — RolesGuard does an exact match on role alone, so a MEMBER-role account can’t reach worker routes regardless of what its (inactive) WorkerProfile looks like. The two differ only in guard + what they touch on isTrainee:

• revokeWorker — any active worker, POST members/:id/revoke-worker. Leaves isTrainee untouched (so reinstatement resumes exactly as they left off, trainee or not).
• demoteTraineeToMember — isTrainee = true profiles only (400 otherwise — “use revoke-worker instead”), POST members/:id/demote-trainee. Explicitly clears isTrainee, since ending trainee status is the point of this action.

Both use AdminGuard + MEMBERS_WRITE.

Reinstatement (promoteToWorker): now checks workerProfile?.status === ACTIVE (not mere existence) before rejecting with “already registered as a worker” — a member with an INACTIVE profile is eligible again. buildOrReactivateWorkerProfile() reuses the existing row instead of creating a new one: department and status are always set from the call, but profession/yearJoinedWorkforce are only overwritten if explicitly supplied this time (otherwise the prior values are kept), and completedSOD/completedBibleCollege/isTrainee are never touched by this path at all — they simply carry over. Audit-logged as WORKER_REINSTATED (vs WORKER_PROMOTED for a genuinely new profile) so the trail distinguishes the two. bulkPromoteToWorker uses the same helper and ACTIVE-only guard for consistency.

Login/refresh gating (auth.service.ts): the “worker account suspended” check is scoped to member.role === WORKER — it used to fire whenever any workerProfile existed with a non-ACTIVE status, which would have wrongly blocked login for a plain MEMBER carrying a leftover INACTIVE profile from a prior revoke/demotion. Applied identically in validateMember, validateRefreshToken, and its rotated-token-replay path.

Pastor

A pastoral designation on a member, independent of WorkerProfile/Department — a pastor may have no department (e.g. a Lead Pastor) or may separately also be an HOD. At most one row per member (OneToOne on member).

Managed via POST/PATCH/DELETE /members/:id/pastor (see Member Module). Surfaced on MemberDto as pastorType: PastorTypeEnum | null, computed from the pastor relation.

MemberImportJob

Tracks a single bulk-import spreadsheet upload from preview through commit.

MemberImportRow

One row of a MemberImportJob’s source spreadsheet.

Event

A church gathering on a specific date.

Venue

A named, reusable physical location. Referenced by EventConfig.defaultVenue and optionally overridden per slot via ServiceSlot.venueOverride.

Deleting a venue that is set as defaultVenue on any EventConfig is rejected by the DB FK constraint. Deleting a venue that is a slot-level venueOverride sets that field to null (SET NULL).

ServiceSlot

The actual check-in target within an event. One event can have multiple slots.

Override columns: workerCheckinStartOverride, workerLateOverride, memberCheckinStartOverride, checkinStopOverride, allowedDistanceOverride

effectiveVenue: computed as slot.venueOverride ?? slot.config.defaultVenue. Throws 400 if neither is set.

EventConfig

A reusable timing template assigned to service slots. Venue is now a first-class relation rather than raw lat/lon.

Constraint: workerLateOffset > workerCheckinStartOffset and checkinStopOffset > workerLateOffset

Attendance

One record per member per event. Workers and members both receive one attendance record per event; workers are distinguished by a LATE status if they arrive after the threshold.

Unique constraint: (member, event) — one record per person per event.

Streak rules:

• PRESENT, LATE, and ATTENDED_ONLINE all count as present and increment the streak.
• ON_LEAVE is neutral — it neither increments nor breaks the streak.
• ABSENT breaks the streak.

Department

DepartmentLead

Joins a WorkerProfile to a Department as head or assistant lead.

PastorFeedback

Weekly structured feedback a department’s HOD or Assistant HOD (D_HOD) submits, which a pastor can read and respond to — from both the admin portal and the mobile app.

Unique constraint: (department, weekOf) — one submission per department per week. Editing after submission is a PATCH on the same row; there’s no draft/submitted status or read-receipt lock.

Ownership check (submission/edit): the caller must be an HOD or Assistant HOD (DepartmentLead row) of the target department — checked via DepartmentLead.exists({ workerProfile, department }), mirroring the isHod check in auth.service.ts:getProfile(). Not gated by RolesGuard/@Roles(WORKER) alone, since being a worker isn’t sufficient — must specifically lead that department.

Ownership check (pastor response): the caller must have a Pastor record (pastorRepo.exists({ member: { id } }), any PastorTypeEnum). Available via both the admin portal (an Admin account whose linked Member has a Pastor record) and the mobile app (any member with a Pastor record).

PrayerRequest

A private prayer request submitted by any member/worker — visible only to the submitter, Prayer department workers, and pastors.

Testimony

An opt-in-public testimony — either tied to one of the submitter’s own prayer requests, or general.

PregnancyPrayerCase

Tracks a pregnant woman receiving ongoing prayer support — created and managed by the Prayer team (or pastors), not self-submitted. Lives in the same src/prayer-request/ module and reuses PRAYER_READ/PRAYER_WRITE — no new permission.

PregnancyPrayerVisit

A log entry recorded each time the Prayer team prays with/visits a pregnant woman — mirrors the FirstTimerVisit idiom in the Follow-Up module.

RequestLeave

ChurchClass

Delete guard: Deleting a class is blocked if any enrolment record exists (any status — IN_PROGRESS, COMPLETED, or CANCELLED). This preserves historical enrolment data. A class with enrolment history cannot be deleted.

ClassType

Replaces the old hardcoded ChurchClassTypeEnum — class types are now admin-creatable and admin-editable, not a fixed set. ChurchClassTypeEnum still exists in code purely as a reference for the migration’s seed data; it’s not used at runtime anymore (removed from the generic /enums endpoint’s churchClassTypes key for the same reason — it no longer reflects reality once admins add their own types).

Promotion chain: nextClassType is a self-referencing pointer, not a level number — a class type either points to the next type in its progression or is null (standalone, no promotion). The chain is entirely admin-configured via the ClassType CRUD endpoints; nothing is pre-wired by the migration (the 5 seeded legacy types — Believers’ Class, Baptismal Class, Workers in Training, Bible College, School of Discipleship — all seed with nextClassType = null). Writes are validated server-side against self-reference and cycles (walks the proposed chain up to 20 hops looking for a loop back to the type being edited) since a DB FK can’t express “no cycles.”

ClassEnrollment

Unique constraint: (member, churchClass)

Level promotion: When an enrollment is COMPLETED and its class’s classType.nextClassType is set, GET classes/enrollments/:enrollmentId/promotion-candidate reports eligibility plus any currently-open (ACTIVE) classes of that next type. Promotion itself is a separate, explicit, admin-confirmed action — POST classes/enrollments/:enrollmentId/promote (body: targetClassId) — mirroring the promoteToWorker pattern (transaction + CLASS_LEVEL_PROMOTED audit log entry + a class-level-promotion templated email to the member). Nothing is auto-enrolled on completion; standalone class types (no nextClassType) simply have no promotion affordance.

Certificates: Once an enrollment is COMPLETED, PATCH classes/enrollments/:enrollmentId/certificate (body: optional certificateNumber) marks it as having received a certificate — sets certificateIssued = true, certificateIssuedAt = now(), and stores certificateNumber if given. This is a manual, admin-confirmed record only (no file upload); it logs CLASS_CERTIFICATE_ISSUED.

Announcement

AnnouncementReaction

A member’s emoji reaction to an announcement they received.

Unique constraint: (announcement, member) — one reaction per member per announcement. Reacting again with a different emoji updates the existing row rather than adding a second one (not Slack-style multi-emoji-per-user).

Group

GroupMember

Join entity between Group and Member. @Unique(['group', 'member']) prevents duplicate membership rows.

Migration note: AddGroupsModule originally created these FK columns as created_by/added_by. Neither entity has an explicit @JoinColumn, so SnakeNamingStrategy.joinColumnName (which names join columns as <relation>_<referencedColumn>) expects created_by_id/added_by_id at runtime — the mismatch caused column grp.created_by_id does not exist whenever the relation was selected (e.g. the announcements list with audience=GROUP). Fixed by migration FixGroupsForeignKeyColumnNames, which renames both columns; per the immutable-migrations rule the original AddGroupsModule file was left untouched.

BirthdayWish

Persists birthday wishes permanently, grouped by year. The birthday announcement expires but wishes remain readable indefinitely.

Unique constraint: (recipient, sender, year) — one wish per sender per recipient per year.

AdminRole

A named role in the admin RBAC system. Carries a list of permissions.

Admin

Links a church member to an admin role. This is the portal-access record — it is separate from the member’s church role (MEMBER/WORKER).

Relationship: A church worker can also be an admin. Having role=WORKER on the Member entity and an Admin record are independent. Mobile app routes check role=WORKER; admin portal routes check the admins table.

Email notifications:

• POST /admin/users (grant) — sends a welcome-admin email to the member containing their email address and the admin portal login URL. Password is not re-generated; the message instructs the user to log in with their existing account password.
• POST /admin/users/:id/revoke — sends an account-deactivated email to the affected member.

AuditLog

Immutable record of every admin write action.

Indexes: action, actor (FK column actorId), targetId, createdAt.

Write path: AuditLogService.log() enqueues a job on the audit-log Bull queue (fire-and-forget, 3 attempts, exponential backoff). AuditLogProcessor handles the actual DB write asynchronously. Failed writes are retained in Redis (removeOnFail: false) and visible in Bull Board.

Actor traceability: The actor relation is a real FK to the members table. When building an audit log API, load the relation (relations: ['actor']) to access actor name and email. If the member account is deleted, actor is set to null but the log record and all other fields are preserved.

EmailLog

Append-only delivery record written by the Bull email processor on every terminal outcome (success or permanent failure). Used for debugging delivery issues and compliance — answers “was this OTP email actually sent?”.

Written by: @OnQueueCompleted (status = sent) and @OnQueueFailed (status = failed, only on the final attempt after all retries are exhausted). Transient failures that Bull subsequently retries do not produce a log row — only the final outcome is recorded.

Indexes: recipient, status, createdAt.

Audit Actions: ADMIN_CREATED · MEMBER_SIGNED_UP · MEMBER_LOGIN · MEMBER_LOGOUT · ADMIN_LOGIN · PASSWORD_CHANGED · PASSWORD_RESET_REQUESTED · PASSWORD_RESET_COMPLETED · ADMIN_PASSWORD_RESET · WORKER_PROMOTED · WORKER_REVOKED · MEMBER_ACTIVATED · MEMBER_DEACTIVATED · MEMBER_UPDATED · MEMBER_CREATED_BY_ADMIN · MEMBER_PHOTO_UPDATED · MEMBER_PHOTO_REMOVED · ATTENDANCE_ADMIN_MARKED · PRAYER_REQUEST_SUBMITTED · PRAYER_REQUEST_STATUS_UPDATED · TESTIMONY_SUBMITTED · DEVICE_PURGED · DEVICE_RESET_REQUESTED · DEVICE_RESET_COMPLETED · ANNOUNCEMENT_CREATED · ANNOUNCEMENT_UPDATED · ANNOUNCEMENT_DELETED · EVENT_CREATED · EVENT_UPDATED · EVENT_DELETED · NOTE_CREATED · NOTE_UPDATED · NOTE_DELETED · LEAVE_APPROVED · LEAVE_REJECTED · DEPARTMENT_CREATED · DEPARTMENT_UPDATED · DEPARTMENT_DELETED · DEPARTMENT_LEAD_ASSIGNED · DEPARTMENT_LEAD_REMOVED · WORKER_PROFILE_UPDATED · ADMIN_ROLE_CREATED · ADMIN_ROLE_UPDATED · ADMIN_ROLE_DELETED · ADMIN_USER_CREATED · ADMIN_USER_UPDATED · ADMIN_USER_DEACTIVATED TITHE_BATCH_QUEUED · TITHE_UNMATCHED_RESOLVED · TITHE_UNMATCHED_DISMISSED · TITHE_DISPUTE_APPROVED · TITHE_DISPUTE_REJECTED · TITHE_ACCOUNT_CREATED · TITHE_ACCOUNT_UPDATED · FINANCE_CATEGORY_CREATED · FINANCE_CATEGORY_UPDATED · FINANCE_REQUEST_CREATED · FINANCE_REQUEST_APPROVED · FINANCE_REQUEST_REJECTED · FINANCE_PROOF_ATTACHED · TITHE_PROOF_SUBMITTED · TITHE_PROOF_CONFIRMED · TITHE_PROOF_DECLINED · TITHE_PROOF_EXPIRED_PURGED · CHURCH_SETTING_UPDATED · INCIDENT_REPORT_CREATED · INCIDENT_REPORT_STATUS_UPDATED · ASSET_CREATED · ASSET_UPDATED · ASSET_MAINTENANCE_SCHEDULED · ASSET_MAINTENANCE_LOGGED · ASSET_INVENTORY_UPDATED

EventReminder

Optional reminder schedule attached to a service slot. Multiple reminders can be configured per slot (one per interval preset).

Unique constraint: (serviceSlot, intervalPreset) — one reminder per preset per slot.

SundaySchoolClass

A permanent Sunday School class. Members are assigned indefinitely (no graduation).

Delete guard (class): Blocked if any members are assigned or any sessions have been recorded. Remove all members and sessions before deleting.

Delete guard (session): Blocked if any attendance records exist for the session. Sessions with attendance cannot be deleted — this prevents silent cascade-deletion of historical attendance data.

SundaySchoolMember

Links a church member to a Sunday School class.

Unique constraint: (member, sundaySchoolClass)

SundaySchoolSession

One session (meeting) of a Sunday School class.

Unique constraint: (sundaySchoolClass, sessionDate)

SundaySchoolAttendance

One attendance record per member per session.

Unique constraint: (session, member)

ChildAgeGroup

Defines an age bracket for automatic child classification.

Delete guard: Deleting an age group is blocked if any child profiles are directly assigned to it or to any of its class groups. This prevents silent orphaning — the admin must reassign or remove the affected children first. Internally, ChildClassGroup rows CASCADE on age-group delete; ChildProfile.ageGroup and ChildProfile.classGroup are SET NULL on delete.

ChildClassGroup

A physical class room or group within an age group.

Delete guard: Deleting a class group is blocked if any child profiles are currently assigned to it. Reassign children before deleting.

ChildProfile

The central record for a registered child.

ChildGuardian

A guardian or authorised pickup person for a child.

ChildCheckIn

One check-in/check-out record per child per session.

TitheAccount

Finance-team-managed list of bank accounts members can pay tithes into. Each account carries its own currency so the church can accept payments in multiple currencies (e.g. NGN, USD).

Indexes: idx_tithe_accounts_account_number, idx_tithe_accounts_currency, idx_tithe_accounts_is_active.

TitheUploadBatch

A batch record created when the finance team uploads an Excel file of tithe payments. Each batch is tied to a specific TitheAccount, so all records in the batch are credited to that account.

TitheRecord

A confirmed tithe payment matched to a member.

Duplicate detection: (memberId, paymentDate, amount) — if all three match an existing record, the row is flagged as a dispute instead. The destination bank account is inherited from the batch’s titheAccount.

Indexes: member_id, batch_id (single-column). Composite IDX_tithe_records_member_payment on (member_id, payment_date) for member giving history range queries.

TitheUnmatchedRecord

Rows from a batch where no member matched the email address.

TitheDisputeRecord

Rows that matched a member but would duplicate an existing TitheRecord.

TithePaymentProof

A member-submitted proof of tithe payment awaiting finance-team review. Files are stored in Cloudinary and automatically purged after a configurable number of days (default 90, controlled by TITHE_PROOF_EXPIRY_DAYS).

FinanceCategory

Admin-managed list of expense categories used on finance requests.

FinanceRequest

An expense request raised by a department head (HOD).

FirstTimer

A visitor recorded by a follow-up team worker or admin during or after a service.

FollowUpTask

A task assigned to a follow-up team worker to engage a first-timer or online non-responder.

Round-robin assignment: The worker in the FOLLOW_UP department with the fewest open tasks (PENDING or IN_PROGRESS) is automatically selected. If no eligible worker exists, the API returns 400.

FollowUpNote

A note added by the assigned worker during follow-up interactions.

FirstTimerVisit

Records each return visit a first-timer makes before or after converting.

Convert

An evangelism outreach contact — not assumed to be an existing Member. See the Evangelism Module section below.

ConvertFollowUpLog

One row per contact attempt with a convert — mirrors FirstTimerVisit.

Sermon

Link-based sermon archive entry — no file uploads. See Sermon Module for the “Announce Live” trigger.

ServiceProgramme

One programme per service slot (unique constraint on service_slot_id). Status flows: DRAFT → LIVE → COMPLETED.

GET /service-programme and GET /service-programme/:id responses also include derived (non-persisted) fields for the admin frontend: serviceSlotId, serviceSlotName ("{eventName} — {slotName}"), and slotCount.

ServiceProgrammeSlot

Ordered items within a programme. Frozen when session starts; runtime changes go to ServiceSessionSlot.

ServiceSession

One session per programme (unique constraint on programme_id). Created when a session starts.

Redis anchor (session:{sessionCode}:anchor, TTL 48 h after completion):

{ "currentSlotPosition": 0, "slotStartedAt": 1718000000000, "slotBaseSeconds": 0,
  "status": "LIVE", "isPaused": false, "pausedAt": null }

Clients compute elapsed = slotBaseSeconds + (Date.now() - slotStartedAt) / 1000. No server-side ticker.

ServiceSessionSlot

Snapshot of each programme slot at session start. Runtime overrides stored here; planned data stays on ServiceProgrammeSlot.

ServicePauseEntry

One row per pause event during a session.

ServiceActionEntry

Audit log of all control actions taken during a session.

ServiceProgrammeTemplate

Auto-upserted when a session with saveAsTemplate = true completes. Minister assignments are always blank — only structure is saved.

ServiceHeadcount

Physical attendance count record for one service slot, broken down by demographic group.

Computed field: total is not stored. It is computed on every read as the sum of all five fixed columns plus all values in customGroups. The value is appended to each response object.

PrayerProgram

A named, configurable prayer program. All prayer entities (day configs, rules, meetings, roster entries) are scoped to a program, enabling multiple concurrent programs (e.g. “Morning Intercessory” for workers and “Friday Night” open to all members).

Audience rules: WORKERS-audience programs use auto-assign; MEMBERS-audience programs use self-selection and manual assignment only; ALL programs combine both.

PrayerScheduleConfig

Global configuration for the prayer roster module (legacy — predates multi-program support). One active record at a time. New installations use PrayerProgram.selectionWindowDays instead.

PrayerDayConfig

Defines which days of the week prayer meetings occur and their capacity/mode, scoped to a program.

Unique constraint (application-level): Only one active config per (program, dayOfWeek) pair.

PrayerScheduleRule

Configurable rules that govern frequency and capacity requirements, scoped to a program.

Seeded defaults (on the default program): worker frequency = 1, HOD frequency = 2, D_HOD frequency = 2, min leaders per meeting = 1, max per meeting = 5.

PrayerFixedAssignment

Permanently pins a worker to a specific prayer day across all months, within a program.

Unique constraint: (workerProfile, dayConfig) — one fixed assignment per worker per day config.

PrayerMeeting

One concrete meeting per calendar date generated from a day config, scoped to a program.

PrayerRosterEntry

One assignment of a worker or member to a prayer meeting. Exactly one of workerProfile or member is set; the other is null.

RentalFacility

A bookable space (hall, room, etc.) owned by the congregation.

RentalPricingTier

One discount rule per member category. Unique on memberCategory.

RentalAddon

Bookable extras (LED screen, décor, etc.) with an optional asset link.

RentalCalendarBlock

Admin-created blackout period on a facility (maintenance, church events, etc.).

RentalBooking

A member’s booking of a facility for a specific time window. Price snapshot is stored at creation time so later config changes do not affect existing bookings.

RentalBookingAddon

Junction between a booking and selected add-ons. Stores unit price/caution snapshots.

RentalPayment

One payment line per booking (service fee + separate caution record if caution > 0). Tracks proof and refund lifecycle.

Game

A reusable Kahoot-style quiz definition — created on the admin portal, can back multiple GameSessions over time. department/churchClass are categorization only, not access control (see Games Module).

GameQuestion

GameSession

One “run” of a Game. sessionCode is the join credential (GAME-XXXXXX).

GameParticipant

A member’s membership in one GameSession, with their running score. @Unique(['session','member']) — joining again just returns the existing row.

GameResponse

One row per (session, question, participant) answer — the unique constraint is the DB-level backstop against double-answering. Individual responses are not audit-logged (too high-frequency/low-stakes).

Unique constraint: (session, question, participant).

4. Authentication & Authorization

Dual-Surface Sessions

The app has two independent entry points — the mobile app (POST /auth/login) and the admin portal (POST /auth/admin-login) — and each maintains its own session row in member_sessions. The surface column (MEMBER | ADMIN) is the discriminator; a unique constraint on (member_id, surface) ensures at most one active session per surface per user.

JWT payload now includes aud (audience) to identify the surface:

{ "sub": "<memberId>", "role": "MEMBER|WORKER", "aud": "MEMBER|ADMIN" }

Surface enforcement:

• JwtStrategy calls validateAccessToken(sub, aud) — it looks up the session row for that specific (memberId, surface) pair. An admin token used on a mobile endpoint checks the ADMIN session; if the user has no admin session, the request is rejected with 401.
• AdminGuard additionally checks request.user.surface === 'ADMIN'. A member token (aud: MEMBER) used on an admin-portal endpoint is rejected with 403 before the admin DB lookup even runs.
• POST /auth/logout is surface-scoped: it reads req.user.surface from the validated token and deletes only that session row, leaving the other surface’s session intact.
• Password reset and device reset/purge invalidate both surfaces simultaneously (credential change = full sign-out).

There is no ADMIN role in the JWT. Admin portal access is determined at the route level by AdminGuard looking up the admins table.

validateAccessToken returns MemberAuth which is set as req.user. For WORKER-role members, req.user.workerProfileId is populated from the loaded workerProfile.id. Worker-facing endpoints that need the worker’s profile ID read it from req.user.workerProfileId — this is never embedded in the JWT itself. HOD status is not carried on MemberAuth; it is resolved once on GET /auth/me (see above) and can be cached by the client. Server-side HOD-gated endpoints query department_leads directly when they need it.

Guards

• ThrottlerGuard — applied globally via APP_GUARD. Rate-limits every endpoint to THROTTLE_LIMIT requests per THROTTLE_TTL_MS-millisecond window per IP (defaults: 100 req / 60 s). Returns HTTP 429 when the limit is exceeded. The GET /health endpoint is exempt via @SkipThrottle(). GET /service-session/:code/state and GET /service-session/:code/slots/:position are overridden to 300 req/60s via @Throttle() — these are public, read-only routes; the override exists for the initial page-load fetch and the (now much less frequent) safety-net poll each live-session view keeps as a fallback — see the Socket.IO section below for why per-IP throttling was never the real scaling lever for this module, since a per-IP cap does nothing to bound aggregate load across the hundreds of distinct devices/IPs a single popular session’s Audience view can attract.
• JwtAuthGuard — applied globally via APP_GUARD. All routes are protected unless decorated with @Public().
• PasswordChangeRequiredGuard — applied globally via APP_GUARD (runs after JwtAuthGuard). Blocks all requests with HTTP 403 PASSWORD_CHANGE_REQUIRED if the authenticated user has changedPassword = false (i.e. they are on a system-generated temporary password). Exempt routes must be decorated with @SkipPasswordChangeCheck(): POST /auth/refresh, POST /auth/logout, GET /auth/me, POST /auth/change-password.
• RolesGuard — applied per-route via @Roles(MemberRoleEnum.WORKER). Checks request.user.role for worker-only routes (mobile app).
• AdminGuard — applied per-route via @UseGuards(AdminGuard). First checks request.user.surface === 'ADMIN' (rejects member tokens with 403), then queries the admins table to verify an active Admin record, then checks @RequiresPermission(AdminPermission.X) metadata. Sets request.admin for downstream use. Used exclusively on admin portal routes.
• LocalAuthGuard — used on POST /auth/login (mobile) and POST /auth/admin-login (web portal) to invoke the Passport local strategy.
• RefreshJwtAuthGuard — used on POST /auth/refresh.

Token Lifecycle

Refresh token delivery and transport differ by surface:

1. Login → receives access_token + requires_password_change (and refresh_token in body for mobile only). A surface-scoped session row is created (or updated) with a hashed refresh token. If requires_password_change is true, the client must redirect the user to POST /auth/change-password before allowing any other action.
2. Access token expires → call POST /auth/refresh. Admin web clients rely on the httpOnly cookie (sent automatically); mobile clients send the refresh token in the Authorization: Bearer header. The refresh token carries aud and renews the same-surface session.
3. Logout → clears the session row for the caller’s surface. For the ADMIN surface the httpOnly cookie is also cleared. The other surface’s session is unaffected.

Admin cookie secure/sameSite flags are NODE_ENV !== 'development', not NODE_ENV === 'production'. The admin web app calls the API cross-site with withCredentials: true, which requires secure: true; sameSite: 'none' — browsers drop any cookie without those flags on a cross-site request. Railway always serves over HTTPS regardless of environment name, so test/staging deployments need the same secure cookie behavior as production; only local dev runs over plain HTTP and needs the relaxed lax/non-secure cookie. Checking === 'production' previously meant any other deployed NODE_ENV value (e.g. test) silently downgraded to a cookie that cross-site browsers refuse to send back on refresh, dropping the admin session on every refresh call.

Refresh Token Rotation & Reuse Detection

Every call to POST /auth/refresh performs a full rotation:

• A new refresh token is issued and its hash replaces the previous one in member_sessions.
• The previous hash, plus the full token response that was just issued and the rotation timestamp, are stored together in Redis under rt_rotated:{memberId}:{surface} for the duration of the refresh token’s TTL.
• If an already-rotated token is presented (i.e. the hash matches the Redis entry but not the current session hash), the server checks how long ago the rotation happened:
  • Within the reuse grace window (10s) — treated as a benign concurrent-request race, not theft (e.g. two browser tabs on the same admin login, or the proactive pre-expiry refresh racing a reactive 401-triggered refresh). The server does not rotate again or touch the session; it replays the exact tokens issued by the rotation that already happened, so both callers converge on the same valid pair.
  • Outside the grace window — treated as credential reuse, the server immediately invalidates the entire session for that surface, and returns HTTP 401. This limits the blast radius of a stolen refresh token to a single use.
• On reuse detection (outside the grace window) the member receives a session-security-alert email advising them to change their password if the sign-out was unexpected.

Absolute Session Lifetime

Each session row in member_sessions is upserted per member + surface — updateLogin() reuses the existing row across logins rather than creating a new one, updating only hashedRefreshToken/lastLogin/lastLogout. createdAt (from BaseEntity) is therefore set once at the row’s first-ever login and never moves again — it is not a valid anchor for “how long has this login been going.” On every refresh request, validateRefreshToken checks:

Date.now() - session.lastLogin > SESSION_MAX_AGE_DAYS × 86 400 000 ms

(Anchored on lastLogin, which resets on every login, not createdAt — using createdAt would mean any member whose session row is older than SESSION_MAX_AGE_DAYS gets force-logged-out on the very first refresh after every future login, no matter how recently they signed in.)

If the threshold is exceeded the session is invalidated and HTTP 401 is returned, forcing a fresh login regardless of how recently the token was rotated. SESSION_MAX_AGE_DAYS defaults to 30 and is configurable via environment variable.

Temporary Password Flow

All new accounts — whether created via signup or admin-elevated — receive a server-generated temporary password. The changedPassword flag on Member is set to false. On first login:

• The login response includes "requires_password_change": true.
• The PasswordChangeRequiredGuard blocks every subsequent authenticated request except the four exempt routes above.
• The user must call POST /auth/change-password (supplying the emailed temporary password as oldPassword) to activate full access.
• Once changed, changedPassword is set to true and normal access resumes.

Signup: POST /auth/signup no longer accepts a password field. The server generates a secure random password, hashes it, sets changedPassword = false, and emails the plaintext temporary password to the new member.

Device Lock (Mobile App)

Only one device may be logged into the mobile app per member account. This prevents proxy check-ins.

• POST /auth/login requires a deviceId string in the request body (the mobile client’s device fingerprint).
• On the member’s first login (member.deviceId is null), the device is registered and login succeeds.
• On subsequent logins, the incoming deviceId is compared to the stored value. If they match, login succeeds. If they differ, HTTP 403 is returned.
• An admin can purge the device lock via DELETE /admin/members/:id/device (MEMBERS_WRITE permission). This sets deviceId = null and invalidates all active sessions for that member, forcing a fresh login from any device.
• POST /auth/admin-login (web portal) does not perform a device check — it is web-first.

Self-Service Device Reset Flow

A member who needs to log in from a new device (lost phone, factory reset, etc.) can reset their own device lock without admin involvement, subject to a rate limit.

1. POST /auth/device-reset/request — accepts { email, newDeviceId }. Rate-limited per email (default: 3 attempts per 24-hour window, configurable via DEVICE_RESET_MAX_ATTEMPTS and DEVICE_RESET_WINDOW_SECONDS). Generates a 6-digit OTP, stores an Argon2 hash and the newDeviceId in device_reset_otps, and emails the code. Always returns the same success message to avoid leaking account existence.
   • Security note: newDeviceId is locked in at request time. An attacker who intercepts the OTP cannot redirect the reset to their own device — the device is bound to whoever initiated the request.
2. POST /auth/device-reset/verify — accepts { email, otp }. Verifies the OTP, checks expiry, marks the record as used, updates member.deviceId to the newDeviceId stored on the OTP record, invalidates all active sessions, and sends a confirmation email. On success the member must log in fresh from the new device.
   • If the attempt count reaches the configured maximum, the email is rate-limited and the member must contact an admin for an out-of-band device purge (DELETE /admin/members/:id/device).

Forgot Password / OTP Reset Flow

1. POST /auth/forgot-password — rate-limited (default: 3 attempts per hour, configurable via env). Generates a 6-digit OTP, stores an Argon2 hash in password_reset_otps, and emails the code. Always returns the same success message to avoid leaking account existence.
2. POST /auth/reset-password — rate-limited (5 attempts/min, same as forgot-password). Verifies the OTP against the hash, checks expiry (default: 15 min for a self-requested reset — longer for a tenant-welcome OTP, see below), marks the OTP as used, updates the password, invalidates any existing session, and emails a confirmation. On success the user must log in fresh.

This endpoint is also how a brand-new tenant’s first admin sets their initial password — see “Tenant Welcome / Set Password Flow” below.

Self-Service Email Change Flow

A logged-in member/worker can change their own email address without admin involvement. Unlike the forgot-password and device-reset flows above, both routes require an authenticated session (JwtAuthGuard via the global guard, no @Public()) — the OTP is a second factor confirming ownership of the new mailbox, not a way to prove account ownership from scratch.

1. POST /auth/email-change/request — accepts { newEmail }. Returns 409 Conflict if newEmail is already used by another member. Rate-limited the same way as forgot-password (checkOtpRateLimit, keyed on the caller’s member id). Deletes any prior unused request, generates a 6-digit OTP, stores an Argon2 hash and the target newEmail in email_change_otps (mirrors DeviceResetOtp’s pattern of locking in the sensitive value at request time), and emails the code to the new address (not the current one) — this doubles as proof the caller controls it.
2. POST /auth/email-change/confirm — accepts { otp }. Verifies the OTP and expiry (OTP_TTL_SECONDS) against the caller’s own most recent unused record, re-checks that newEmail is still unclaimed (409 on a race), marks the record used, updates member.email to the stored newEmail, and emails a confirmation to the new address.

Tenant Welcome / Set Password Flow

Neither public entry point — self-serve POST /signup nor platform-admin POST /platform/tenants — collects a password for the tenant’s first admin. SignupDto has no adminPassword field at all: letting an unauthenticated signup form set a password directly would mean anyone could submit an email address they don’t own, with no proof of control over that inbox. TenantProvisioningService.provision()/seedTenantAdmin() still branches on whether adminPasswordHash was supplied, but in practice only one caller ever supplies it today — the provision:tenant CLI script (src/provision-tenant.ts), an internal ops tool run by trusted staff, not a public HTTP surface:

• No adminPasswordHash supplied (both POST /signup and POST /platform/tenants, i.e. the normal case): seedTenantAdmin() generates a random password via UtilityService.generateRandomPassword() and hashes it — this password is never revealed to anyone, including the caller who triggered provisioning. changedPassword: false. It also generates a 6-digit OTP and stores its hash in password_reset_otps (the same table the forgot-password flow uses) with a 48-hour expiry (WELCOME_OTP_TTL_HOURS) — deliberately longer than the 15-minute forgot-password OTP, since a new admin may not check their email the same day. Once the tenant is active, provision() fire-and-forgets a warm welcome email (tenant-welcome template) to the new admin containing the OTP and a discuva-admin (formerly Faithapp-admin) /set-password?email=...&otp=... link. That page pre-fills the code and calls the existing POST /auth/reset-password — the same endpoint and verification logic the forgot-password flow uses, just reached from a different starting point. The longer OTP window is offset by rate-limiting POST /auth/reset-password itself (5 attempts/min). Clicking that link and setting a password is also, in effect, email verification — nobody can ever log in to a self-serve-signed-up tenant without proving control of the inbox behind adminEmail.
• adminPasswordHash supplied (CLI only): changedPassword: true, no OTP generated, no welcome email sent.

Async Tenant Provisioning + Onboarding State Machine

TenantProvisioningService.provision() (CREATE SCHEMA + run the tenant migration set + seed the first admin + create a Subscription) runs async, on a Bull queue (TENANT_PROVISIONING_QUEUE, TenantProvisioningProcessor) for self-serve POST /signup only. POST /platform/tenants runs it inline — see “Platform-admin tenant creation is synchronous” below for why the two callers deliberately differ. provision() itself is unchanged either way and still callable directly (the provision:tenant CLI script does) — it’s already idempotent (checks existing state before acting at every step), which is what makes it safe for the queue to retry and safe to re-run by hand after a synchronous failure.

Tenant.onboardingStatus (PENDING | PROVISIONING | ACTIVE | FAILED) is orthogonal to isActive — isActive still means “currently allowed to serve live traffic” (also flipped by PlatformTenantService.suspendTenant); onboardingStatus only ever moves forward through the lifecycle once and never changes on suspend/reactivate.

Self-serve signup flow (async):

1. TenantProvisioningService.ensurePendingTenant(subdomain, churchName, parentTenantId?) — the find-or-create part of the old provision(), now its own method — creates the Tenant row (onboardingStatus: PENDING) or returns the existing one if resuming. Callable standalone specifically so SignupController gets a real tenant.id back before handing off to the queue.
2. recordEvent(tenantId, 'SIGNUP_INITIATED', SELF_SERVE) — see the audit trail note below.
3. A TENANT_PROVISIONING_JOB is enqueued (ProvisionTenantParams + tenantId + actorType/actorId + branchInviteToken), attempts: 3, backoff: { type: 'exponential', delay: 5000 } (this codebase’s standard retry convention, e.g. TitheProcessor).
4. TenantProvisioningProcessor sets onboardingStatus = PROVISIONING, records PROVISIONING_STARTED, calls provision() (unchanged), then on success sets onboardingStatus = ACTIVE (provision() already flips isActive), records PROVISIONING_COMPLETED, and consumes the branch invite (BranchInviteService.markAccepted, moved here from SignupController since the controller no longer awaits completion). On permanent failure (all 3 attempts exhausted, via @OnQueueFailed()) sets onboardingStatus = FAILED and records PROVISIONING_FAILED with the error message in metadata.
5. GET /signup/:tenantId/status (@Public()) — polled by the caller until status is ACTIVE (or FAILED). Unauthenticated by design, same reasoning as POST /signup itself; excluded from TenantMiddleware alongside it in TenantModule (a caller may not be on the tenant’s own subdomain yet — e.g. a marketing site). Confirmed live this exclude needs a named path parameter (v1/signup/:tenantId/status), not a bare (.*) wildcard mid-path — this project’s path-to-regexp version throws PathError on boot for that shape; only a suffix wildcard like v1/platform/(.*) is accepted.

Platform-admin tenant creation is synchronous. PlatformTenantService.createTenant() calls ensurePendingTenant() + recordEvent('PLATFORM_ADMIN_INITIATED', PLATFORM_ADMIN, { actorId }), then calls provision() directly and awaits it inline — no queue, no polling. On success it sets onboardingStatus = ACTIVE and records PROVISIONING_COMPLETED; on failure it sets onboardingStatus = FAILED, records PROVISIONING_FAILED with the error in metadata, and rethrows so the platform admin sees the real error immediately instead of a silently-stuck PENDING row. This was deliberately reverted from an earlier async design: unlike self-serve signup, this is a trusted, authenticated action by a platform admin, there’s no fraud-review gate that would need to sit between “created” and “actually provisioned,” and CREATE SCHEMA + migrations + seeding is fast enough that the admin can just wait for the response.

Platform-level audit trail (TenantOnboardingEvent, tenant_onboarding_events): distinct from AuditLogService, which is tenant-scoped (lives in each church’s own schema, actor FKs to that tenant’s own Member) and can’t record an event from before/independent of any tenant schema existing. A small, purpose-built, public-schema table instead: tenant (FK, cascade), event (SIGNUP_INITIATED | PLATFORM_ADMIN_INITIATED | PROVISIONING_STARTED | PROVISIONING_COMPLETED | PROVISIONING_FAILED), actorType (SELF_SERVE | PLATFORM_ADMIN | SYSTEM), actorId (nullable — the platform admin’s id when actorType = PLATFORM_ADMIN), metadata (nullable jsonb). Written via TenantProvisioningService.recordEvent() — no separate service, it’s a simple insert-only log. Viewable per-tenant via GET /platform/tenants/:id/onboarding-events (TENANTS_READ permission). The platform-admin path never emits PROVISIONING_STARTED — there’s no meaningful gap between “initiated” and “started” when both happen inline in the same request.

Response shape: POST /signup returns a PENDING tenant immediately (poll GET /signup/:tenantId/status for completion). POST /platform/tenants returns the tenant already ACTIVE — same shape GET /platform/tenants’ rows use, no polling needed.

Role Elevation

The access token’s role is re-validated from the live database on every request via validateAccessToken. This means if a member is promoted to WORKER, their existing token will reflect the new role on the next request after the DB is updated.

Department Capabilities

Certain modules are gated by a department capability rather than a specific department name or a single free-form key. This is a full replacement of the earlier Department.key-based system: key (a single free-form string, validated against nothing but a preset-suggestion enum) has been removed entirely, in favor of capabilities — a fixed, code-defined, multi-value list. The old system conflated “this department’s organizational label” with “what it unlocks,” forcing an admin to type a magic string that had to exactly match hardcoded values scattered across both the backend and discuva-member mobile, and could only ever grant one capability per department. Capabilities decouple these: a department can be named anything, and separately be given any combination of capabilities via checkboxes in the admin UI.

How it works:

• Each Department has a capabilities: DepartmentCapability[] column (text[], default {}). DepartmentCapability (src/department/enums/department-capability.enum.ts) is a fixed enum — six values today, each named after the action it unlocks rather than a department: MANAGE_SUNDAY_SCHOOL, MANAGE_CHILDREN_CHURCH, MANAGE_PRAYER_REQUESTS, MANAGE_EVANGELISM_CONVERTS, MANAGE_FOLLOW_UP, FRONT_DESK_OPERATIONS. A capability only belongs in this list if a real feature is gated on it — mirrors the KNOWN_MODULES pattern. CreateDepartmentDto/ UpdateDepartmentDto validate capabilities with @IsEnum(DepartmentCapability, { each: true }); unlike the old key, admins pick from a fixed checkbox list, not free text, and a single department can hold more than one capability at once.
• A WorkerProfile has a primary department and an optional secondaryDepartment. A worker has a capability if either department’s capabilities array includes it.
• DepartmentAccessService (src/department/service/department-access.service.ts, exported from DepartmentModule) is the single shared implementation of this check — hasCapability(memberId, capability) (boolean, for composing with other conditions like “or is a pastor” or “or is the class teacher”) and assertHasCapability(memberId, capability, message?) (throws ForbiddenException). Used by 7 services — attendance, evangelism, sunday-school, prayer-request, service-session, children-church, and follow-up — each calling it with its own capability and message; two of those services (evangelism, follow-up) also have an inline duplicate of the same check where they already have the WorkerProfile loaded and calling the service would mean a redundant query.
• GET /auth/me computes a flat capabilities: DepartmentCapability[] field on MemberDto (@Transform, same pattern as pastorType) — a deduped union of the primary and secondary department’s capabilities. discuva-member mobile checks this one field (profile?.capabilities?.includes("X")) instead of independently re-deriving the primary-or-secondary union at every call site.
• HOD (head-of-department) assignment is always restricted to the worker’s primary department (unrelated to capabilities).

Sunday School access — a request passes if any of the following is true:

1. Caller is a WORKER whose primary or secondary department has the MANAGE_SUNDAY_SCHOOL capability.
2. Caller is the appointed teacher of the specific Sunday School class being acted upon.

Admin-only SS routes (delete class/session) use AdminGuard + SUNDAY_SCHOOL_WRITE instead.

Children Church access — a request passes if any of the following is true:

1. Caller is a WORKER whose primary or secondary department has the MANAGE_CHILDREN_CHURCH capability.

Admin-only CC routes (age group/class group CRUD, slot-level check-in report) use AdminGuard + CHILDREN_CHURCH_WRITE/READ instead.

Migration note: 1790208000000-ReplaceDepartmentKeyWithCapabilities.ts backfills the 6 legacy key values that had real behavior behind them (ADMIN, EVANGELISM, SUNDAY_SCHOOL, PRAYER, CHILDREN_CHURCH, FOLLOW_UP) into their corresponding capability, then drops the key column. Any department whose key was one of the other preset values (WORSHIP, USHERING, MEDIA, PROTOCOL, WELFARE, YOUTH, YOUNG_ADULTS) or a custom string had no real behavior behind it and is simply dropped — those departments end up with capabilities: [].

5. Module Reference

Multi-Tenant Request Scoping

Every request except /v1/platform/*, /v1/signup, and the version-neutral /, docs, health routes goes through TenantMiddleware: it resolves the tenant from the Host header’s subdomain (stripped of APP_BASE_DOMAIN, e.g. church-alpha.example.com → church-alpha; localhost in dev, so *.localhost works with no /etc/hosts changes), then wraps the entire rest of the request — guards, interceptors, and the handler — in one DB transaction with SET LOCAL search_path set to that tenant’s schema. Full design in docs/MULTI_TENANT_MIGRATION.md §4.3/§4.4.

Fallback resolution for a fixed, non-wildcard host (added 2026-08, extended to discuva-member 2026-08): discuva-admin is deployed at a single admin.discuva.org origin shared by every tenant, not a per-tenant wildcard — admin is in RESERVED_SUBDOMAINS (src/tenant/utility/extract-subdomain.ts) specifically so no tenant could ever collide with it, but that also means extractSubdomain() always returns null there: there is no subdomain in the Host header to strip. discuva-member has a real per-tenant wildcard for its own hosting ({tenant}.discuva.org, resolved the normal Host-header way, unchanged) but its API calls target the separate, dedicated api.discuva.org host every other app calls directly — same problem, different reason: the Host header TenantMiddleware sees on that call carries no subdomain either. When that happens, TenantMiddleware tries two fallbacks, in order, before giving up with the same 404 Tenant not found as before:

1. A verified JWT tenant claim. Every access/refresh token, both surfaces, embeds tenantId/schemaName in the payload at sign time (AuthService.generateTokens(), reading cls.get('tenantId')/cls.get('schemaName') — already correctly set for that request by whichever mechanism resolved it, Host header or this same fallback on the login request itself). TenantMiddleware checks the Authorization: Bearer header first — trying the access secret, then REFRESH_JWT_SECRET, since a Bearer header can legitimately carry either token type (discuva-admin’s refresh flow sends its refresh token via an httpOnly cookie; discuva-member’s sends it via this same header instead, a pre-existing RefreshJwtStrategy design, not something added for this) — then the refresh_token httpOnly cookie (verified with REFRESH_JWT_SECRET) as a second fallback. Covers every authenticated request, including a bare /v1/auth/refresh call from either app. This is genuinely safe against spoofing: the claim only exists inside a JWT whose signature already proves it came from this server, at a moment CLS already held the correct tenant — there’s no way for a client to write an arbitrary tenantId into a token it can’t forge the signature for.
2. X-Tenant-Subdomain header. discuva-admin sends it on every pre-auth request where no token exists yet: POST /v1/auth/admin-login (needs to know which tenant’s Member/Admin tables to check credentials against before it can issue anything), and POST /v1/auth/forgot-password/reset-password (same reasoning — PasswordResetOtp is tenant-schema-scoped too, and both the “Forgot password” flow on the login screen and the first-time /set-password flow reached from a welcome email are equally pre-auth). discuva-member sends it on every request to api.discuva.org (derived from its own Host header via getCurrentTenantSubdomain(), utils/tenant/api-base-url.ts), not just pre-auth ones — harmless to include always, and it’s what app/manifest.ts’s server-side, pre-auth GET /tenant/info call for PWA branding relies on, since no JWT exists there yet either. This header is not cryptographically trusted the way the JWT claim is — it’s exactly as trustworthy as a user typing a workspace URL: a wrong or malicious value just resolves to the wrong (or a nonexistent) tenant’s schema, where the supplied email/OTP/session simply won’t match any real row, so it can never grant access to anything, only ever fail against the wrong place. On an authenticated discuva-member request it’s redundant with (and always loses to) the JWT claim above — sent anyway for the handful of pre-auth calls that need it, and it’s simpler to attach unconditionally than to special-case which requests do.

Both fallbacks are skipped entirely — not even attempted — whenever the Host header itself already resolved a subdomain, so discuva-member’s own hosting (as opposed to its outgoing API calls) is completely unaffected; this exists purely to make a fixed, non-wildcard destination host work for the two kinds of traffic that need one.

Distinct error responses per tenant state, not a single generic 404: the tenant lookup is findOneBy({ subdomain }), deliberately not filtered by isActive, so a row that exists but isn’t (yet, or anymore) usable gets a response that actually explains why, using onboardingStatus (see “Async Tenant Provisioning + Onboarding State Machine” above) to disambiguate:

• No Tenant row at all for the subdomain → 404 Tenant not found (unchanged).
• onboardingStatus is PENDING/PROVISIONING → 503, “This workspace is still being set up. Please check back in a moment.” — this is the common case for a subdomain hit moments after signup, before the queue has finished.
• onboardingStatus is FAILED → 503, “There was a problem setting up this workspace. Please contact support.” — deliberately no technical detail in the public response; GET /platform/tenants/:id/onboarding-events is where that lives.
• onboardingStatus is ACTIVE but isActive is false → 403, “This account has been suspended. Please contact support.” onboardingStatus never reverts once ACTIVE, so this combination only ever means PlatformTenantService.suspendTenant was used — a materially different situation from “still provisioning” that a flat isActive check couldn’t previously tell apart (both 404’d identically before this).
• onboardingStatus === ACTIVE && isActive === true → proceeds normally, as before.

For any new module with tenant-owned tables: register entities with TenantTypeOrmModule.forFeature([...]) (src/tenant/utility/tenant-typeorm.module.ts), not TypeOrmModule.forFeature([...]). Plain TypeOrmModule repositories never see the tenant transaction regardless of request scoping — this is a @nestjs-cls/transactional limitation, not a bug to work around per-call. TenantTypeOrmModule is a drop-in replacement using the same DI token, so @InjectRepository(Entity) call sites in services need no changes. Only genuinely global, public-only tables (Tenant, PlatformAdmin, Plan/Subscription, and similar control-plane entities) should keep plain TypeOrmModule.forFeature().

Scheduler tenant iteration (forEachActiveTenant): @Cron()-decorated methods run with no CLS context at all — there’s no HTTP request for TenantMiddleware to hook into. A tenant-scoped repository called from inside a scheduler with no CLS context silently falls back to the plain public-search-path manager instead of throwing, so without doing anything about it a scheduler processes whatever stale/orphaned rows happen to sit in public, not any real tenant’s data. Every scheduler that touches tenant-scoped data fetches every active Tenant and re-enters that tenant’s context once per tenant via the shared helper forEachActiveTenant(tenantRepo, cls, txHost, logger, fn) (src/tenant/utility/for-each-active-tenant.ts), which wraps the existing runInTenantContext() helper (the same one EmailProcessor already used) in a fetch-loop-catch: fn runs once per active tenant inside that tenant’s cls.runWith(...) + SET LOCAL search_path transaction, and one tenant throwing is caught and logged without stopping the rest of the batch. Any distributed Redis lock a scheduler already had (e.g. lock:pledge-reminders) still wraps the whole @Cron method across all tenants, unchanged — it guards against two app instances racing, not tenants racing each other. A service that opens its own dataSource.transaction() inside a scheduler needs extra care: a fresh top-level transaction doesn’t inherit the outer SET LOCAL search_path (likely a different pooled connection) and would silently write to the wrong schema — such call sites are rewritten to use the ambient this.txHost.tx manager instead (see AttendanceService.markAbsentees() and RecurringEntryScheduler, the latter wrapping each recurring entry in its own Postgres SAVEPOINT so one entry’s failure doesn’t abort the whole tenant’s batch). BranchRollupScheduler predates this helper and hand-rolls the identical fetch-loop pattern itself; YoutubeSubscriptionScheduler and SubscriptionLapseScheduler’s top-level query are exempt because their data is genuinely control-plane (public-schema), not tenant-owned.

CORS origin validation (createCorsOriginValidator): wildcard-subdomain tenancy means the set of valid frontend origins is unbounded — a new tenant’s subdomain is valid to call the API the moment it’s provisioned, so a static CORS_ORIGINS allowlist can never enumerate them all (and previously didn’t try to — it silently rejected every tenant subdomain origin that wasn’t hand-added to the list, a real bug, not just a gap). src/main.ts’s app.enableCors(), ServiceSessionGateway, and GameSessionGateway all now validate the incoming Origin header dynamically via the shared createCorsOriginValidator() (src/tenant/utility/cors-origin-validator.ts): allow if the origin’s hostname equals APP_BASE_DOMAIN or ends in .${APP_BASE_DOMAIN} — the exact same suffix logic extractSubdomain() uses for tenant resolution, so “is this origin allowed to call the API” and “does this host resolve to a tenant” can never disagree — with a small explicit CORS_ORIGINS allowlist checked first for origins that don’t fit the pattern (a separate marketing site, API docs, internal ops tooling). Requests with no Origin header (curl, server-to-server calls, mobile apps) are always allowed, matching the previous behavior. Custom domains (a tenant’s own domain, e.g. giving.theirchurch.org) don’t end in APP_BASE_DOMAIN and are rejected by this check today — deliberately deferred, same as tenant_domains itself (see Custom Domains note below); adding support means a second branch in createCorsOriginValidator() checking a cached set of verified custom domains before falling through to reject (must stay cached, not a live DB query — this runs on every request/connection).

Custom domains (deferred, not built): docs/MULTI_TENANT_MIGRATION.md earmarks a future tenant_domains table for letting a church map their own domain (giving.theirchurch.org) to their tenant, instead of only their-church.<APP_BASE_DOMAIN>. Not built — subdomain routing is sufficient for now. When it is: (1) resolve the custom domain to the tenant’s canonical subdomain via a new lightweight public endpoint, cached client-side, so discuva-member’s getCurrentTenantSubdomain() (utils/tenant/api-base-url.ts) can resolve it to the same subdomain it already sends as X-Tenant-Subdomain today — no changes needed to CLS/SET LOCAL search_path/ tenant-scoped repos, all of that stays subdomain-keyed; (2) a domain must be DNS-verified (TXT record token, or requiring it already point at this infrastructure) before being trusted — a row in the table must never be sufficient on its own, since nothing stops a tenant from entering a domain they don’t control; (3) TLS is an infrastructure decision independent of this codebase — a single wildcard cert covers every subdomain automatically, but each custom domain needs its own certificate (e.g. a reverse proxy that automates ACME/Let’s Encrypt on demand, or requiring the tenant sit behind a proxy like Cloudflare that terminates TLS for them) — nothing here provisions that.

Auth Module

Routes: POST /auth/signup, POST /auth/login, POST /auth/admin-login, POST /auth/refresh, POST /auth/logout, GET /auth/me, POST /auth/change-password, POST /auth/email-change/request, POST /auth/email-change/confirm, POST /auth/forgot-password, POST /auth/reset-password, POST /auth/device-reset/request, POST /auth/device-reset/verify

POST /auth/email-change/* require an authenticated session (member or worker) — see Self-Service Email Change Flow above for the full request/confirm sequence.

Route separation: POST /auth/login is for the mobile app (members & workers) and enforces device lock — deviceId is required. POST /auth/admin-login is for the web admin portal — it verifies that the caller has an active Admin record and has no device check. Both routes use the same Passport LocalAuthGuard for credential validation.

Member Module

Manages the universal identity. Admin portal routes (list members, promote/revoke workers, change status, reset passwords) are now guarded by AdminGuard + the appropriate MEMBERS_READ or MEMBERS_WRITE permission.

Routes prefix: /members

Admin-created members: POST /members (AdminGuard + MEMBERS_WRITE) lets an admin create a plain MEMBER account directly — for members without a phone/email habit, or who otherwise can’t complete self-signup. Body is SignupDto (same DTO as POST /auth/signup). MemberService.createByAdmin shares its implementation with signup() via a private createMemberRecord helper: same temp password generation, changedPassword: false (forces the change-password flow on first login), and welcome-member email with the temp password/login URL. The only difference is the audit action — MEMBER_CREATED_BY_ADMIN (with the admin as actorId) instead of MEMBER_SIGNED_UP. Promoting the new member to a worker afterwards is a separate step — use the existing POST /members/:id/promote.

Self-service profile edit: PATCH /members/me (JwtAuthGuard only, no admin) lets a member/worker update their own firstname, lastname, phoneNumber, gender, birthDay, birthMonth, birthYear, maritalStatus (UpdateMyProfileDto, all fields optional). Deliberately excludes email (handled by the OTP-gated email-change flow — see Self-Service Email Change Flow), and the admin-only church-record fields dateJoinedChurch, yearBornAgain, yearBaptized, baptizedWithHolyGhost.

Pastor designation: three AdminGuard + MEMBERS_WRITE routes manage the optional Pastor relation on a member (same permission as promote-to-worker — no separate permission was introduced):

• POST /members/:id/pastor — body { type: PastorTypeEnum } — assigns the designation; 409 Conflict if the member is already a pastor.
• PATCH /members/:id/pastor — body { type: PastorTypeEnum } — changes the type; 404 if the member is not a pastor.
• DELETE /members/:id/pastor — removes the designation; 404 if the member is not a pastor. Returns 204.

pastorType: PastorTypeEnum | null is surfaced on MemberDto (GET /auth/me, GET /members/:id, GET /members, GET /members/workers), computed from the pastor relation.

Profile photo: POST /members/me/photo (multipart, field photo) uploads/replaces the caller’s own photo via CloudinaryService (folder profile-pictures); DELETE /members/me/photo removes it. Both JwtAuthGuard only — self-service, no admin permission required. DELETE /members/:id/photo (AdminGuard + MEMBERS_WRITE) lets an admin clear another member’s photo for moderation. All three return the updated MemberDto. Audit-logged as MEMBER_PHOTO_UPDATED / MEMBER_PHOTO_REMOVED, with metadata: { self: true|false } distinguishing a member’s own action from an admin’s.

Member Bulk Import

Lets an admin create many members at once from a spreadsheet, via a preview-then-commit flow so validation errors can be reviewed before anything is written. Controller: MemberImportController, all routes AdminGuard + MEMBERS_WRITE.

Routes prefix: /members/bulk-import

Commit is batched, not per-row. commitImport resolves duplicate-email and department-name lookups for the entire batch in 2 queries up front (not one of each per row), then inserts every still-eligible row’s Member (+ WorkerProfile, if applicable) in a single transaction. This means a row can still independently fail pre-validation (email taken since preview, unknown department) and land in failedRows exactly as before, but a row that passes pre-validation and is included in the transaction is no longer isolated from the others — a genuine DB-level failure during the bulk insert (e.g. a race-condition constraint violation) fails the whole commit rather than just that one row, unlike the old per-row-transaction implementation. In practice this only matters for the rare case a pre-validated row fails for a reason pre-validation couldn’t catch.

Template columns: First Name*, Last Name*, Email*, Phone Number, Gender (MALE/FEMALE), Birth Day (1-31), Birth Month (1-12), Birth Year, Marital Status (SINGLE/MARRIED/DIVORCED/WIDOWED), Year Born Again, Year Baptized, Baptized With Holy Ghost (TRUE/FALSE), Date Joined Church (YYYY-MM-DD), Department (optional — creates the member as a Worker), Profession, Year Joined Workforce.

Validation (at preview time, one pass over every row):

• Each row is validated against SignupDto’s rules (required fields, formats).
• Duplicate email within the file is flagged, pointing at the earlier row number.
• Email already existing in the DB is flagged.
• A filled department column is looked up case-insensitively; an unknown department name is flagged as an error (Unknown department: "...") and the row is excluded from commit.
• job.validRows = rows with zero errors; only those are eligible for commit.

Commit behavior: re-checks each valid row’s email uniqueness and department lookup (guards against a race between preview and commit); on a per-row failure the row is marked FAILED with commitError set and processing continues with the remaining rows rather than aborting the whole job. A job can only be committed once — re-committing an already-COMMITTED job returns 400 Bad Request.

Admin Module

Manages the admin RBAC system used by the admin web portal. This module is @Global() — its providers (AdminGuard, AdminService, AdminRoleService) are available across the entire app without explicit module imports.

AdminRole routes (/admin/roles):

• GET /admin/roles — ADMIN_READ — list all roles
• GET /admin/roles/:id — ADMIN_READ — get role by ID
• POST /admin/roles — ADMIN_WRITE — create role
• PATCH /admin/roles/:id — ADMIN_WRITE — update role
• DELETE /admin/roles/:id — ADMIN_WRITE — delete role (blocked if active admins use it)

Admin user routes (/admin/users):

• GET /admin/users — ADMIN_READ — list all admin users
• GET /admin/users/me — any admin — own admin profile
• GET /admin/users/:id — ADMIN_READ — get admin by ID
• POST /admin/users — ADMIN_WRITE — grant admin access to a member
• PATCH /admin/users/:id — ADMIN_WRITE — change admin role or active status; an admin cannot modify their own record (403)
• POST /admin/users/:id/revoke — ADMIN_WRITE — soft-revoke admin access (isActive = false)

Security notes:

• Admin user read endpoints (GET /admin/users, GET /admin/users/me, GET /admin/users/:id) strip password and deviceId from the joined Member before returning — these fields are never returned to API clients.
• Role-change audit entries capture the previous and new role name in addition to the changed field list.

Predefined role seed (migration): A one-time migration (SeedPredefinedAdminRoles) seeds 9 ready-to-use roles covering the typical org structure. The migration is idempotent — it uses ON CONFLICT ("name") DO NOTHING so re-running it on a database that already has these roles is safe.

Default seed: On application bootstrap, if DEFAULT_ADMIN_EMAIL is set and no admin exists with that email, the system creates:

1. A Member with role = MEMBER and changedPassword = false
2. A SuperAdmin AdminRole carrying all permissions
3. An Admin record linking the two

Church Settings Module

Lets an admin turn optional feature modules on/off per-installation without a deploy — the mechanism that keeps the platform usable by congregations that don’t run every ministry this codebase supports. Backed by ChurchSetting (key unique, value: jsonb = { enabled: boolean, displayName?: string }), read through ChurchSettingsService with a short-TTL cache (cacheService) so isEnabled() checks on every request don’t hit Postgres each time.

KNOWN_MODULES (src/church-settings/constants/known-modules.constant.ts) is the fixed list of togglable modules, each with a required: boolean. required: true modules (departments, service_programme) can never be disabled — PATCH /admin/settings/:key returns 400 if attempted. Everything else defaults to required: false: incident_report, asset_management, evangelism, follow_up, pastor_feedback, prayer, sunday_school, children_church, facility_rental, tithe, classes, announcements. A module with no row in the database is treated as enabled (absent = on) — a fresh install has everything available until an admin opts out.

displayName override: an admin can rename a module’s label (e.g. “Pastor Feedback” → “Elders’ Feedback”) via the same PATCH /admin/settings/:key body without touching enabled. ChurchSettingsService.upsert() merges rather than overwrites — passing { enabled } alone preserves whatever displayName was previously set (a toggle flip must never silently blank out a custom label). Both frontends fall back to the module’s default label when displayName is unset.

Enforcement (ModuleEnabledGuard + @RequiresModule(key)): mirrors the existing AdminGuard + @RequiresPermission idiom — @RequiresModule('evangelism') sets metadata via Reflector, and ModuleEnabledGuard (added into the controller’s existing @UseGuards([...]) array, not a separate decorator call) reads it and calls isEnabled(), throwing 403 if the module is off. Applied at the controller level across every optional module’s admin and member-facing controllers, so a disabled module is fully unreachable via the API, not just hidden in the UI.

GET /modules/state (JwtAuthGuard, any authenticated member/worker/admin) is the one shared source of truth for “is module X on,” returning { key, enabled, displayName }[] for every known module (displayName falls back to the module’s default label). Both discuva-admin’s sidebar and discuva-member mobile’s Explore/Ministry/Leadership tiles read from this single endpoint (useModuleState() hook, near-identical implementation in both frontends) rather than each frontend independently guessing module state — the same duplication risk already seen once with discuva-admin’s hardcoded permission-group list (see Admin Module’s AdminPermissionGroups note below).

AdminPermissionGroups visibility tied to module state: each AdminPermissionGroup (see AdminPermission enum reference) optionally carries a moduleKey. discuva-admin’s role-permission picker (app/admin-management/page.tsx) and the read-only permission display (app/profile/page.tsx) both filter PERMISSION_GROUPS/AdminPermissionGroups through isModuleEnabled(group.moduleKey) before rendering — an admin is never offered permissions for a feature that’s disabled for their church. Core, non-toggleable groups (Members, Events & Venues, Departments, Attendance, Finance, Administration, etc.) carry no moduleKey and are always shown.

Routes prefix: /admin/settings (admin CRUD), /modules/state (shared read endpoint, all authenticated roles)

Event Module

Manages events and service slots. Events can be single or recurring (daily/weekly/monthly). At least one serviceSlot is required at creation — each slot carries an optional configId pointing to an EventConfig. For recurring events the same slot template (including configId) is stamped onto every generated occurrence; updating the config later propagates to all check-ins that reference it.

CreateEventDto takes no eventDate/endDate fields — Event.eventDate/endDate are always derived from the supplied serviceSlots (eventDate = earliest startTime, endDate = latest endTime, both UTC-date-truncated so the result doesn’t depend on server timezone). This applies on both create (including each recurring occurrence, computed from its own offset-shifted slots) and update (whenever serviceSlots is replaced). There is no longer a “manual” date range independent of the slots — previously a caller could set an event date range that didn’t match its slot times (e.g. editing a slot’s time left the event’s dates stale), which this removes by construction.

Routes prefix: /events, /event-config

Each slot can have multiple reminder schedules via sub-resource /events/slots/:slotId/reminders (admin-only). See EventReminder model.

Admin frontend UX (discuva-admin, app/events/page.tsx): since the event’s date range is entirely derived from its slots’ times (no manual override, per above), the create/edit form’s SlotRow sets min on the datetime-local inputs (a slot’s End Time can’t be earlier than its own Start Time; each slot after the first has its Start Time’s min set to the previous slot’s End Time, since slots run in sequence) — but min on type="datetime-local" only reliably restricts the browser’s calendar date view; the time-of-day spinner on an already-valid date isn’t blocked interactively in Chrome/most browsers, only flagged :invalid on blur/submit, which read as “not working” for the time portion. updateSlot() therefore also clamps values in JS the instant they change: a slot’s End Time snaps forward to match its Start Time if set earlier, a slot’s Start Time snaps forward to the previous slot’s End Time if set earlier (pulling its own End Time along if that would now precede it), and moving a slot’s End Time later pulls the next slot’s Start Time forward with it if it would otherwise fall behind. min is kept alongside this for the calendar-level hint; the JS clamp is what actually prevents an invalid time-of-day from sticking. Neither replaces backend validation, which still governs what’s actually accepted on submit.

Reminder dispatch (cron */15 * * * *): Queries EventReminder rows where enabled = true, lastSentAt IS NULL, fireAt <= now, and slot.startTime > now. The filter runs entirely in SQL — fireAt is pre-computed at reminder creation (and recalculated if intervalPreset is updated). When a slot is deleted or recreated (e.g., event update), its reminders are cascade-deleted. On create, fireAt = slot.startTime − preset_minutes. On update with a new intervalPreset, fireAt is recalculated from the existing slot’s startTime.

Service slot ordering: EventService.getAll(), getById(), and getUpcomingEvents() all explicitly order the serviceSlots relation by startTime ASC (query-builder .addOrderBy('serviceSlots.startTime', 'ASC') for getAll; TypeORM’s relation order option for the other two, e.g. order: { serviceSlots: { startTime: 'ASC' } }). Without this, a joined one-to-many relation has no guaranteed order — First/Second Service could come back in either order depending on DB/join internals, which showed up as the admin portal’s event list not consistently showing slots in the order they begin.

Venue Module

Manages named venue records referenced by event configs and individual service slots. Venues decouple location data from event creation — create a venue once, reference it by ID in any config or slot.

Routes prefix: /venues
ADMIN: create, update, delete
Any authenticated user: list (full, unpaginated — admin-controlled reference data), get by ID

Attendance Module

Check-in window logic:

• Window opens: slot.startTime + workerCheckinStartOffsetSeconds (workers) or + memberCheckinStartOffsetSeconds ( members)
• Window closes: slot.startTime + checkinStopOffsetSeconds (same for all)
• Workers are LATE if they check in after slot.startTime + workerLateOffsetSeconds
• Members are always PRESENT if within the window

Distributed absence-marking lock: The every-5-minute cron job acquires a Redis SET NX EX 270 lock before running. If a second instance starts while the first is running, it sees the lock and skips silently. The TTL (270 s) is shorter than the cron interval (300 s) so the lock self-expires if the process crashes mid-run. Department-scoped history endpoints (/history/department, /department/event/:eventId) are automatically scoped to the caller’s own department via their lead-role assignment — no departmentId query parameter is accepted or needed.

Duplicate check-in: The (member, event) unique constraint is enforced at DB level. If a member tries to check in twice for the same event, the service catches the QueryFailedError (PG error code 23505) and returns 409 Conflict with the message “You have already checked in for this event.”

Event data on absent records: Absence records have serviceSlot = null (no physical slot was entered). History endpoints (GET /attendances/my-history, GET /attendances/history, GET /attendances/history/department) join the event relation directly on the Attendance entity rather than through serviceSlot, so event is always populated regardless of status.

Lifetime summary (GET /attendances/my-summary), computed in SQL not client-side: Returns { totalCount, presentCount, attendanceRatePercentage, lastCheckedInDate, attendanceStreak } for the calling member, via AttendanceService.getMyAttendanceSummary. This exists because the mobile app previously derived rate and streak from whatever page of /attendances/my-history it had fetched (e.g. the last 10 records) — correct only for a member with 10 or fewer lifetime records, silently wrong for anyone else. attendanceRatePercentage and totalCount/presentCount are a single aggregate query (COUNT/SUM(CASE WHEN status IN (...))) over the member’s entire history (not date-windowed, unlike the admin-dashboard-facing getPersonalAttendancePercentage which defaults to a 30-day window) — ON_LEAVE records are excluded from both numerator and denominator (an approved leave shouldn’t count against the rate), and PRESENT/LATE/ATTENDED_ONLINE all count as attended. attendanceStreak delegates to the existing getAttendanceStreak (walks the last 500 records newest-first, skip ON_LEAVE, break on ABSENT) — already used by the dashboard and already covered by the (member, roleAtCheckin, createdAt) composite index, so no new index was needed for this endpoint.

Admin-assisted attendance (AttendanceService.adminMarkAttendance): one action covers two cases — checking in a member/worker with no phone (no Attendance row exists yet for that member+event), and “restoring a streak” for someone auto-marked ABSENT by the absence-marking cron (a row already exists — this just updates it). There’s no separate streak field to repair: attendanceStreak is always computed live from Attendance rows (see getAttendanceStreak above), so fixing/creating the row is the fix. If a record already exists for (member, event) its status/serviceSlot are updated and checkinTime is left untouched if already set; otherwise a new record is created with checkinTime = now, roleAtCheckin = the member’s current role, and location: null (this is an assisted check-in, not GPS-verified). Reachable two ways:

• POST /attendances/admin/mark — admin portal, AdminGuard + ATTENDANCE_WRITE.
• POST /attendances/department/mark — mobile app, JwtAuthGuard only, gated in-service by assertIsAdminDeptWorker() (the caller’s workerProfile.department or secondaryDepartment must have the FRONT_DESK_OPERATIONS capability — the same capability idiom already used by ServiceSessionService.assertIsAdminDeptWorker). Front-desk/Admin-department workers get this without needing an admin-portal login.

Both routes take { memberId, serviceSlotId, status } (AdminMarkAttendanceDto) — the slot determines the event (slot.event), matching how self-check-in (POST /attendances/checkin) already resolves it. Audit-logged as ATTENDANCE_ADMIN_MARKED.

Mobile member picker for admin-assisted check-in (GET /attendances/department/search-members?q=): deliberately narrow — gated by the same assertIsAdminDeptWorker() check, bounded to 10 results (MemberService.searchActiveMembersLite), and returns only id/firstname/lastname/role (no email or phone) since this is a lookup for “which person is standing in front of me,” not a general member directory. This is the one exception in the codebase to “no non-admin member-search endpoint” — justified because the whole point of this flow is finding one named person on the spot; it’s scoped tightly enough (Admin-department workers only, minimal fields, capped results) that it doesn’t reopen a general member-picker surface.

Email export (POST /attendances/export-email): same shared pattern as /service-headcount/export-email — filters the same query GET /attendances/history already runs (no pagination), builds an .xlsx, and emails it via the report-export template.

Leaderboard chart (discuva-admin, app/attendance/page.tsx): the Leaderboard tab has a Table/Chart toggle — Chart renders a horizontal present/absent bar per worker via the same components/charts/bar-chart.tsx wrapper introduced for the headcount trends charts. No new backend aggregation — GET /attendances/leaderboard was already aggregate-shaped (presentCount/absentCount per worker).

Routes prefix: /attendances

Department Module

Departments are the workforce units. Each can have a head and assistant lead assigned from its worker members. The optional key field on a department links it to a module-access category (e.g. SUNDAY_SCHOOL, CHILDREN_CHURCH, MEDIA). Multiple departments can carry the same key.

GET /departments returns the full list (unpaginated) — department count is admin-controlled and bounded. Workers by department (GET /departments/:id/workers) remains paginated as it can be large.

Routes prefix: /departments

Pastor Feedback Module

A weekly, structured feedback channel from departments up to the pastorate — the department’s HOD or Assistant HOD (D_HOD) submits it; a pastor reads and responds, from either the admin portal or the mobile app.

Three controllers, one service:

• pastor-feedback-worker.controller.ts (JwtAuthGuard) — POST /pastor-feedback (submit), PATCH /pastor-feedback/:id (edit own), GET /pastor-feedback/my (own history). Ownership is checked in-service (HOD/D_HOD of the target department), not by role alone.
• pastor-feedback-admin.controller.ts (AdminGuard) — cross-department browse/edit/delete (PASTOR_FEEDBACK_READ/WRITE), plus POST /pastor-feedback/admin/:id/respond for an admin whose linked Member has a Pastor record.
• pastor-feedback-pastor.controller.ts (JwtAuthGuard, mobile-facing) — same cross-department browse plus POST /pastor-feedback/pastor/:id/respond, gated by assertIsPastor() (any Pastor record) rather than an admin permission.

Weekly reminder scheduler (PastorFeedbackReminderScheduler): @Cron('0 9 * * 1', { timeZone: CHURCH_TIMEZONE }) — Monday 9am. Computes weekOf as the Monday of the week that just closed, finds every Department with no PastorFeedback row for that week, and emails + pushes a reminder to the department’s HOD (falling back to the D_HOD if no HOD is assigned; skipped entirely if neither exists). Unlike PrayerReminderScheduler, no reminderSent boolean is needed — the row’s absence is the “still pending” signal, and push de-duplication relies on PushNotificationService’s idempotencyKey (pastor-feedback-reminder:{departmentId}:{weekOf}).

Routes prefix: /pastor-feedback, /pastor-feedback/admin, /pastor-feedback/pastor

Rename data-migration note: the original Department Feedback → Pastor Feedback rename only renamed the AdminPermission enum values in code (department_feedback:read/write → pastor_feedback:read/write) — it did not touch already-granted AdminRole.permissions (a raw text[] column checked via a plain .includes() in AdminGuard, not a normalized join table). Any role granted the old strings before the rename silently lost access with no error. Fixed by 1788998400000-FixStalePastorFeedbackPermissions.ts, which array_replaces the old strings for the new ones on every existing admin_roles row. General lesson: any future rename of an AdminPermission enum value needs a matching data-migration for admin_roles.permissions, not just the code rename — the enum change alone never reaches rows that already exist.

Prayer Request Module

Lets any member/worker submit a private prayer request and, separately, share an opt-in public testimony — either tied to one of their own prayer requests or general. This is distinct from the Prayer Roster Module below, which schedules workers into prayer-meeting duty slots; this module is member-submitted requests with a lifecycle (OPEN → PRAYED_FOR → ANSWERED), unrelated to any meeting.

Visibility:

• Prayer requests are visible only to the submitter, workers in the Prayer department, and pastors — never a public wall. Testimonies default to private; the submitter alone decides at submission time whether theirs appears on the shared public feed (isPublic) — there is no separate admin moderation/publish step.

Entities: PrayerRequest (prayer_requests) and Testimony (testimonies), both with a nullable member FK (SET NULL) plus a submittedByName snapshot, mirroring PastorFeedback.submittedBy’s pattern so a deactivated member’s history survives. A Testimony.prayerRequest FK (nullable, SET NULL) links it to a specific request; null means a general testimony not tied to any request.

Three controllers, one service (PrayerRequestService):

• prayer-request-worker.controller.ts (JwtAuthGuard) — POST /prayer-requests (submit), GET /prayer-requests/mine (own history), POST /testimonies (submit, optional prayerRequestId — enforced to be the caller’s own request), GET /testimonies/mine, GET /testimonies/public (the opt-in feed, open to any authenticated member/worker).
• prayer-request-team.controller.ts (JwtAuthGuard, mobile-facing) — GET /prayer-requests/team, PATCH /prayer-requests/team/:id/status. Gated in-service by assertIsPrayerTeamOrPastor(): any worker whose primary or secondary department has the MANAGE_PRAYER_REQUESTS capability, or any member with a Pastor record.
• prayer-request-admin.controller.ts (AdminGuard) — GET /prayer-requests/admin, PATCH /prayer-requests/admin/:id/status, GET /testimonies/admin (full visibility, not just public ones). Reuses the existing PRAYER_READ/PRAYER_WRITE permissions (already grouped under “Prayer Roster” in AdminPermissionGroups) — no new permission was introduced, since this is the same overall “Prayer” domain.

Routes prefix: none fixed — routes span /prayer-requests* and /testimonies* across the three controllers (each controller uses @Controller() with a full path per handler rather than a single shared prefix, since the two resources don’t share one).

Pregnancy prayer tracking: the same module also tracks pregnant women receiving ongoing prayer support — PregnancyPrayerCase (name, EDD, details, status) plus PregnancyPrayerVisit (a log entry per prayer/visit, mirroring the FirstTimerVisit idiom in the Follow-Up module). Unlike prayer requests, these are created and managed entirely by the Prayer team/pastors on the woman’s behalf — there is no worker-facing self-submit controller. PregnancyPrayerCase.lastPrayedAt is denormalized and updated whenever a new visit is logged, so the UI can show “last prayed” without joining the visit log on every read. Reuses PRAYER_READ/PRAYER_WRITE — no new permission. Every PregnancyPrayerVisit is also readable back via GET prayer-requests/team/pregnancy-cases/:id/visits (mobile) and GET prayer-requests/admin/pregnancy-cases/:id/visits (admin, PRAYER_READ) — paginated, newest first, so the full visit-and-note history is reviewable, not just the denormalized lastPrayedAt date. Routes: GET/POST prayer-requests/team/pregnancy-cases, POST prayer-requests/team/pregnancy-cases/:id/visit, PATCH prayer-requests/team/pregnancy-cases/:id/status, GET prayer-requests/team/pregnancy-cases/:id/visits (mobile, assertIsPrayerTeamOrPastor gated) and the parallel GET prayer-requests/admin/pregnancy-cases, PATCH prayer-requests/admin/pregnancy-cases/:id/status, GET prayer-requests/admin/pregnancy-cases/:id/visits (admin portal oversight, read + status-only — case creation and visit logging stay Prayer-team/mobile-only by design).

Leave Module

Workers request leave with a date range. Approved leave is checked by the cron job: if a worker has approved leave overlapping a slot’s time range, they are marked ON_LEAVE instead of ABSENT.

Submission guards:

• A worker with a PENDING request cannot submit another until the first is actioned.
• A worker cannot submit a request whose date range overlaps any already-approved leave (dateFrom ≤ request.dateTo AND dateTo ≥ request.dateFrom). Returns 400 Bad Request.

Date columns (dateFrom, dateTo): stored as PostgreSQL date (no time component, format YYYY-MM-DD). Overlap checks compare date strings to avoid timezone shifts.

Routes prefix: /leave

Classes Module (displayed as “Training Classes”)

Tracks member progress through structured church programs. The module, route path (/classes), and permission keys (classes:read/classes:write) are unchanged — only the user-facing label was renamed from “Classes”/“Church Classes” to “Training Classes” (sidebar nav, breadcrumbs, page headings, permission labels). Renaming the permission enum keys would strand existing admin_roles.permissions rows (see the Pastor Feedback rename note under the Pastor Feedback Module section), so only display strings changed.

Class types: admin-defined via ClassType CRUD (/classes/types) — not a fixed enum. Each type optionally points to a nextClassType, forming an admin-configured promotion chain (see the ClassType entity section above). Deactivating a type (isActive: false) hides it from new-class pickers without breaking existing classes that reference it.

Enrollment statuses: IN_PROGRESS → COMPLETED or CANCELLED. A COMPLETED enrollment whose class type has a nextClassType becomes eligible for level promotion (GET classes/enrollments/:id/promotion-candidate → POST classes/enrollments/:id/promote) — an explicit, separate, admin-confirmed action, not automatic.

Certificates: A COMPLETED enrollment can be marked as having received a certificate via PATCH classes/enrollments/:id/certificate (optional certificateNumber) — see the ClassEnrollment entity section above.

Study material (ChurchClass.documentUrl): optional, admin-set link to the class’s syllabus/manual (Google Drive, PDF link, etc.) — validated as a URL (@IsUrl()) at the DTO level, but the URL itself can come from three places: a plain external link typed in directly, a fresh upload (POST classes/materials/upload, multipart, field name file), or reusing a URL already in use by another class (GET classes/materials/library — distinct documentUrls across all classes, each with the list of class names currently using it, so the admin doesn’t re-upload the same manual per class type). Upload accepts PDF, Word, PowerPoint, or image mimetypes; size is capped by MAX_CLASS_MATERIAL_UPLOAD_BYTES (env var, default 10 MB — separate from the app-wide MAX_FILE_UPLOAD_BYTES default of 5 MB since course material tends to run larger than proofs/images). Uploaded files land in Cloudinary’s class-materials folder. Whichever source produced the URL, it’s set the same way afterward — documentUrl on POST/PATCH classes.

Assignments (Assignment/AssignmentSubmission, tables assignments/assignment_submissions): each ChurchClass can have any number of assignments. An assignment has title, optional instructions, maxScore (default 100), optional dueDate, and isPublished (default true — an unpublished assignment is an admin-only draft, invisible to students and not submittable). A student submits free-text content against a published assignment; one submission per member per assignment (UNIQUE(assignment_id, member_id)) — resubmitting before grading overwrites the existing row (submittedAt bumped), but once graded (gradedAt set) further resubmission is rejected with 400, so a grade can’t be silently invalidated by a late edit. Grading (PATCH classes/assignments/submissions/:submissionId/grade) sets score (validated <= assignment.maxScore, 400 otherwise), optional feedback, and stamps gradedBy (the grading Admin, resolved via @CurrentAdmin() — not the JWT’s member id) + gradedAt. gradedBy is SET NULL on admin deletion, mirroring the reviewedBy pattern used by tithe/finance proof review.

Assignments reuse the existing classes:read/classes:write permissions rather than adding new ones — managing assignments is the same admin surface as managing the classes they belong to.

Routes prefix: /classes, /classes/types

Announcements Module

Audience-targeted broadcast messages. The /announcements/feed endpoint filters automatically based on the caller’s role and optional departmentId.

Audience rules:

• MEMBER → sees ALL + MEMBERS_ONLY + any INDIVIDUAL announcements addressed to them + any GROUP announcement for a group they belong to
• WORKER → sees ALL + WORKERS_ONLY + DEPARTMENT (for their department) + INDIVIDUAL (addressed to them) + any GROUP announcement for a group they belong to
• ADMIN → sees all audiences
• Expired announcements (expiresAt < now) are excluded from the feed

Audience types: ALL | WORKERS_ONLY | MEMBERS_ONLY | DEPARTMENT | INDIVIDUAL | GROUP
When audience = DEPARTMENT, departmentId is required. When audience = INDIVIDUAL, targetMemberId (UUID) is required. When audience = GROUP, groupId (UUID) is required.

Push notification on every audience: AnnouncementService.create() always fire-and-forgets a single PushNotificationService.dispatchToMemberIds() call after saving, for every audience type — not just GROUP. resolveMemberIdsForAudience() computes the recipient member-id list per audience (GROUP → GroupService.getMemberIdsForGroup; INDIVIDUAL → the single targetMember; ALL/MEMBERS_ONLY/WORKERS_ONLY/DEPARTMENT → an ACTIVE-member query filtered by role/department, mirroring resolvePhoneNumbers’s SMS-targeting logic but without requiring a phone number on file). No push is sent when the resolved list is empty. Idempotency key = the announcement id, so a retry or duplicate call never double-sends. Failure to dispatch is logged as a warning and never fails the announcement creation itself — the announcement is still visible in-app via the feed regardless of push delivery outcome.

Optional SMS delivery (sendViaSms/smsBody): CreateAnnouncementDto/UpdateAnnouncementDto accept sendViaSms?: boolean and smsBody?: string. Setting sendViaSms: true requires the caller’s admin role to hold the SMS_SEND permission (checked in AnnouncementService, not the DTO — a DTO can’t inspect the caller’s permission set — throws 403 Forbidden otherwise) and requires smsBody to be non-empty. smsBody is deliberately separate from body: the announcement body is often long-form and meant for in-app reading, whereas SMS is billed per segment, so admins compose a distinct, short message for it. On create, an SMS is sent (awaited, not fire-and-forget, since it’s a paid external call whose failure must be caught and logged synchronously) whenever sendViaSms is set. On update, the SMS is sent only on the transition into sendViaSms=true — re-saving an already-SMS’d announcement (e.g. editing its title afterward) does not re-text everyone.

SMS phone number resolution (resolvePhoneNumbers) — independent of the push-notification audience logic above. Always restricted to ACTIVE members with a non-null phoneNumber, further filtered by audience:

• ALL — every eligible member
• MEMBERS_ONLY — role = MEMBER
• WORKERS_ONLY — role = WORKER
• DEPARTMENT — workers whose workerProfile.department matches announcement.department
• INDIVIDUAL — just announcement.targetMember
• GROUP — members resolved via GroupService.getMemberIdsForGroup(announcement.group.id)

resolvePhoneNumbers takes a plain { audience, departmentId?, targetMemberId?, groupId? } target rather than an Announcement entity, so it’s reusable outside the announcement-creation flow — see sendSmsBroadcast below.

SMS-only broadcast (POST /announcements/sms-broadcast), no announcement created: For sending a text blast to an audience without publishing anything to the in-app feed. Guarded solely by SMS_SEND (not ANNOUNCEMENTS_WRITE — an admin with SMS access but no announcement-authoring access can use this). Body: SendSmsBroadcastDto — audience (required) + the matching departmentId/targetMemberId/groupId for DEPARTMENT/INDIVIDUAL/GROUP audiences + message (required). Reuses the same resolvePhoneNumbers targeting as sendViaSms on a regular announcement. No Announcement row is created, no push notification is sent, and no title/body is required — this is purely an SMS send. Returns { sentCount }; sentCount: 0 (not an error) when the resolved audience has no members with a phone number on file. Logs SMS_BROADCAST_SENT to the audit log (metadata: { audience, count }).

Emoji reactions: any authenticated member/worker can react to an announcement with one of a fixed emoji set (ReactionEmojiEnum: 👍 ❤️ 🙏 🎉 👏) via POST announcements/:id/react — reacting again just updates the existing reaction (one per member per announcement, not multi-emoji). DELETE announcements/:id/react removes it. GET announcements/:id/reactions returns { summary: { emoji, count }[], myReaction: string | null } — myReaction reflects the calling member’s own reaction so the frontend can highlight it without a separate lookup. No audit logging on reactions — too high-frequency/low-stakes to be worth an audit trail entry per click.

System-triggered announcements (createSystemAnnouncement): a small internal entry point used by features that need to publish an ALL-audience announcement without going through the admin-authored create() flow — no Admin/SMS-permission check, author is left null (the FK is nullable for exactly this reason), publishedAt is now, and the same persist + push-notify path runs. Used today by the Sermon Archive’s “Announce Live” trigger (see Sermon Module); designed to also be the target of the planned YouTube WebSub livestream-detection integration.

Routes prefix: /announcements

Picking a group when creating a GROUP announcement does not require groups:read/groups:write — the admin frontend’s group picker (GroupSearchInput, a searchable combobox filtering the already-fetched list client-side rather than a plain <select>) calls GET /groups/lookup via useGroupLookup() (see Groups Module), gated on announcements:write only, since choosing a group here is a component of the announcement feature rather than a separate group-management capability.

Groups Module

Reusable, admin-managed rosters of members and/or workers (e.g. “Call Leaders”) used to target announcements at a fixed group of people without re-selecting individuals each time. A group’s membership is independent of Department — a group can mix members and workers from any department.

Entities:

• Group (groups table) — name (unique), description (nullable), createdBy (nullable FK → members, SET NULL).
• GroupMember (group_members table) — join entity. A row is either a real Member (member FK set) or a phone-only entry (phoneNumber + optional label set, member null) — e.g. a manually-typed number, or one imported from a FirstTimer who has no Member account (first-timers can’t join Groups any other way, since they aren’t Member records). Enforced by a CHECK constraint (member_id IS NOT NULL AND phone_number IS NULL OR the reverse) added in migration AddGroupMemberPhoneEntries, plus service-layer logic that only ever sets one side. @Unique(['group', 'member']) and @Unique(['group', 'phoneNumber']) both apply — Postgres treats NULLs as distinct per unique index, so real-member rows (phoneNumber null) and phone-only rows (member null) don’t collide with each other’s constraint. group/member FKs ON DELETE CASCADE (removing a group or a member cleans up membership rows automatically), addedBy (nullable FK → members, SET NULL).

Permissions: groups:read, groups:write (grouped under “Announcements” in AdminPermissionGroups, since a group’s only current purpose is targeting announcements).

Routes prefix: /groups

Resolving a group’s phone numbers for SMS (AnnouncementService.resolveGroupPhoneNumbers, used by both regular announcement sendViaSms and the dedicated SMS-only broadcast): unions two sources — active Members in the group with a phone number on file (via GroupService.getMemberIdsForGroup, then a direct Member query for the active/phone-on-file filter) and raw phone-only entries (GroupService.getPhoneOnlyNumbersForGroup) — deduped via Set. Phone-only entries have no “active” concept; they’re included as-is.

Indexes (migration AddGroupsModule): group_members(group_id) and group_members(member_id) back the roster listing and the group-audience membership check used by the announcement feed’s EXISTS subquery; announcements(group_id) backs the same feed query.

SMS Module

Provider-agnostic SMS sending — pure BYOK, no platform-default account and no prepaid credit balance. A tenant must configure and activate their own SMS provider (Communication Providers below) before they can send at all; there is no fallback. This is deliberate: a platform-run wallet billed in Naira only ever made sense for Nigerian tenants — BYOK lets a tenant in any country pick whichever SMS vendor actually serves them and pay that vendor directly.

Provider abstraction (src/sms/interface/sms-provider.interface.ts):

type SmsProviderCredentials = Record<string, string>; // e.g. Termii's { apiKey, senderId }, Twilio's { accountSid, authToken, fromNumber }

interface ISmsProvider {
  readonly maxRecipientsPerRequest: number; // Termii: 100 (true bulk endpoint); Twilio: 20 (concurrency cap, no bulk endpoint)
  send(to: string[], message: string, encoding: 'plain' | 'unicode', credentials: SmsProviderCredentials): Promise<{ messageId: string; status: string }>;
  getBalance(credentials: SmsProviderCredentials): Promise<{ balance: number; currency: string }>;
  getMessageHistory(credentials: SmsProviderCredentials): Promise<SmsLogEntry[]>;
}

SmsProviderRegistryService (src/sms/service/sms-provider-registry.service.ts, same shape as billing’s PaymentProviderRegistryService) holds every registered vendor simultaneously — termii → TermiiSmsProvider, twilio → TwilioSmsProvider — and SmsService resolves which one to use per call from the tenant’s active TenantCommunicationProviderConfig.providerId, never a hardcoded class. Adding a vendor is a new ISmsProvider class, a line in the registry, and a communication_providers catalog row — no other call site changes.

SmsService:

• calculateSegments(message) — determines encoding and segment count for billing purposes. A message is encoded plain (GSM-7, 160 chars/segment) unless it contains a non-ASCII character or one of the characters Termii documents as forcing UCS-2/unicode encoding even though they’re otherwise ordinary ASCII punctuation: ; ^ { } \ [ ~ ] | € ' " — in which case it’s encoded unicode (70 chars/segment). Returns { segments, encoding, characterCount }.
• send(to, message) — resolves the caller’s active SMS config once (SmsCredentialResolverService.resolveConfig()); if the tenant has none configured, throws 403 SMS_PROVIDER_NOT_CONFIGURED immediately, before attempting anything. Otherwise looks up the matching ISmsProvider from the registry and batches to into groups of that provider’s own maxRecipientsPerRequest. A failed batch is logged and skipped; it does not abort the remaining batches.
• getLogs()/getBalance() — same resolve-or-403 pattern, then pure passthrough to the resolved provider (a tenant sees their own vendor’s balance/history, never the platform’s — there isn’t one).

Message history (TermiiSmsProvider.getMessageHistory): calls Termii’s GET /api/sms/inbox?api_key=... (undocumented pagination or date-filter params — it’s a flat array of every message on the account) and maps its raw field names (receiver, message, status, sms_type, message_id, created_at, sender?) to the provider-agnostic SmsLogEntry shape (recipient, message, status, type, messageId, sentAt, sender?). A non-array response body is treated as empty rather than thrown. TwilioSmsProvider has no native bulk-send endpoint, so it issues one POST per recipient (Promise.all, capped by maxRecipientsPerRequest) and joins the returned sids with a comma for messageId.

Routes prefix: /admin/sms (AdminGuard)

Env vars: TERMII_BASE_URL (default https://api.ng.termii.com) — Termii’s API host is infrastructure, not a secret, so it stays env-driven even under pure BYOK; every tenant’s Termii account (BYOK) talks to the same host. No platform-default credentials exist for any SMS vendor. See Environment Variables.

Communication Providers (Tenant Self-Service BYOK)

Tenant-facing counterpart to Platform Admin’s read-only/catalog-only communication-provider surface — this is what lets a church admin actually set their own SMS/email provider credentials (docs/MULTI_TENANT_MIGRATION.md §Phase 6c’s deferred write side, now built). src/communication-provider/.

Encryption (EncryptionService, src/utility/service/encryption.service.ts): AES-256-GCM, keyed by CREDENTIALS_ENCRYPTION_KEY (hashed via SHA-256 to a real 32-byte key — same min(32)-chars convention as JWT_SECRET, no fixed hex/base64 format required on the operator). Each encrypted value is a self-contained iv:authTag:ciphertext string (all base64) — nothing else needs to be stored alongside it to decrypt later. encryptFields/decryptFields apply this to every value in a flat credentials object, keeping field names (apiKey, senderId, etc.) intact and legible in the stored JSONB while no individual value is ever plaintext. Rotating this key makes every previously-encrypted credential unreadable — there is no re-encryption tooling.

Credential resolution (SmsCredentialResolverService): pure BYOK, no wallet. resolveConfig() looks up the current tenant’s active TenantCommunicationProviderConfig for the sms channel (cached 300s per (tenantId, channel), invalidated immediately on write), decrypts it, and returns { providerId, credentials } — or undefined if the tenant has no active SMS provider configured, which SmsService treats as “can’t send” (403 SMS_PROVIDER_NOT_CONFIGURED), never as “use a default.”

Email credential resolution (EmailCredentialResolverService): same shape as the SMS resolver, email channel — resolveConfig() returns { providerId, credentials, senderIdentity } (or undefined for “use platform default”), cached under the same communication-provider-config:{tenantId}:{channel} key pattern (so TenantCommunicationProviderService’s existing invalidation already covers this without any changes). No wallet — email at church-scale volumes is a rounding error on any provider’s free tier, so there’s no cost to meter (docs/MULTI_TENANT_MIGRATION.md §4.12). providerId matters here in a way it doesn’t for SMS: each provider has an incompatible credential shape ({user, password[, host, port, secure]} for gmail/smtp, {apiKey} for resend/sendgrid, {apiKey, domain} for mailgun), so EmailProcessor has to know which concrete IEmailProvider to hand the decrypted credentials to, not just that BYOK credentials exist. senderIdentity doubles as the email “from” address for a BYOK tenant (falls back to the platform’s EMAIL_FROM/EMAIL_USER when unset).

Email providers (src/utility/email-provider/): five implemented IEmailProvider classes; only gmail, resend, and sendgrid are seeded into the communication_providers catalog (smtp/mailgun exist in code but aren’t tenant-selectable yet — add a catalog row to turn one on) —

sendgrid is Twilio’s actual email product (SendGrid) — catalog name SendGrid (Twilio) — registered alongside twilio (SMS) so a tenant who wants Twilio across both channels can, using each product’s own real credential shape (they’re genuinely separately-credentialed even though one company owns both, so this is two catalog rows, not one shared “Twilio” entry).

gmail’s BYOK credentials accept an optional host/port/secure override on top of user/password — this is what actually lets a tenant route mail through a different domain (Outlook/Office365, Zoho, their own company mail server) rather than being locked to the platform’s own SMTP settings; omitting them reuses the platform’s own host/port/secure/service with just a different mailbox. smtp is for a tenant who wants to fully bring their own server with no platform fallback at all. sendgrid/mailgun call their REST APIs directly via native fetch (no SDK dependency) — SendGrid with Bearer auth, Mailgun with HTTP Basic auth and a FormData body; both throw a clean 500 if neither BYOK nor platform-default credentials are configured, rather than silently no-op-ing.

Routes prefix: /communication-providers (AdminGuard, tenant-scoped — deliberately not under /platform, which is entirely excluded from TenantMiddleware)

Only one active provider per channel: both PUT and PATCH (when activating) run inside a transaction that also deactivates every other provider already active on that same channel for the tenant (TenantCommunicationProviderService.deactivateSiblings) — SmsCredentialResolverService/EmailCredentialResolverService each pick a single isActive = true row per channel, so allowing more than one active at a time would make that pick arbitrary. Turning a provider off never touches its siblings.

Communication Providers: deactivation has real consequences (added 2026-08). A platform admin can activate/ deactivate a provider in the platform-wide catalog (PATCH /platform/communication-providers/:id, PlatformCommunicationProviderService.setActive — see Platform Admin above). Initially this only flipped the CommunicationProvider.isActive column with zero downstream effect anywhere — verified live at the time: neither credential resolver checked it, the tenant-facing catalog endpoint didn’t filter on it, and a tenant already configured against a since-deactivated provider kept sending through it exactly as before. Three changes closed that gap:

1. TenantCommunicationProviderService.listProviders() excludes an inactive provider from the catalog a tenant can newly select — unless that tenant already has a config against it, in which case it stays visible (filtering it out entirely would make an already-configured provider’s row silently vanish from discuva-admin’s page with no explanation, even though its encrypted credentials are still saved).
2. SmsCredentialResolverService/EmailCredentialResolverService now also require provider.isActive = true in the same query that already checks config.isActive = true and provider.channel. A deactivated provider genuinely stops resolving for every tenant using it, not just new ones.
3. PlatformCommunicationProviderService.setActive() invalidates the 300s resolved-credential cache immediately for every tenant with an active config against the provider (communicationProviderCacheKey — extracted as a shared utility, src/communication-provider/utility/communication-provider-cache-key.ts, since four separate places needed the identical cache-key string and three of them were computing it independently before this), rather than leaving affected tenants to keep working for up to 5 more minutes. It also emails those same tenants’ admins — TenantBroadcastService.notifyTenants() (see “Tenant Broadcasts” under Platform Admin above), deliberately targeted at only the tenants actually using this provider, not a platform-wide broadcast — explaining the channel is disrupted (deactivating) or restored (reactivating). A tenant’s own TenantCommunicationProviderConfig row is never touched by any of this — same “don’t retroactively delete something already configured” posture suspendTenant uses for a tenant’s own data.

Env vars: CREDENTIALS_ENCRYPTION_KEY (required, min(32) chars) — see Environment Variables.

Email BYOK send path (EmailProcessor.handleSend, src/utility/processor/email.processor.ts): unlike SMS, which resolves credentials synchronously within the original request, an email send runs inside a Bull job — tenant context isn’t ambient there, so handleSend wraps its entire body in runInTenantContext() (previously only onCompleted/onFailed did this, purely to log) before calling EmailCredentialResolverService.resolveConfig(). Resolves to the concrete IEmailProvider matching the tenant’s providerId if BYOK-configured (falling back to GmailProvider for gmail or any unrecognized id), otherwise the platform’s constructor-injected EMAIL_PROVIDER_TOKEN default. Which provider actually handled a given send is carried back via Bull’s job-return-value convention (job.returnvalue) so onCompleted logs the real provider used to EmailLog.provider, not just the platform default — that can differ per send once BYOK is in play.

Announcement integration: see “Optional SMS delivery” under Announcements Module — sending SMS on an announcement requires the SMS_SEND permission (distinct from SMS_READ, which only allows checking balance/cost).

Tenant Profile Self-Service (src/tenant/)

GET /tenant/info (@Public(), still goes through TenantMiddleware) returns branding for the current subdomain — unchanged. PATCH /tenant/info (AdminGuard, new CHURCH_PROFILE_WRITE permission) is the tenant self-service write side (docs/MULTI_TENANT_MIGRATION.md §Phase 6c’s deferred item, now built) — lets a church admin edit their own name/logoUrl/tagline/address/supportEmail/currency/timezone without going through platform support, which was previously the only way to change any of it (PATCH /platform/tenants/:id, platform-admin-only). Body (UpdateTenantProfileDto) is a partial — every field optional, only provided fields are applied (Object.assign). Deliberately excludes subdomain, schemaName, clusterId, and isActive — platform-controlled, not something a church admin can change about their own tenant.

Logo upload (POST /tenant/logo, DELETE /tenant/logo, both CHURCH_PROFILE_WRITE): logoUrl on PATCH /tenant/info only ever accepted an already-hosted URL — these two routes are the actual upload path, mirroring MemberController’s POST members/me/photo exactly (multer FileInterceptor, 3MB limit, image-mimetype-only filter, CloudinaryService.uploadBuffer into the church-logos folder). Tenant.logoPublicId (new column) tracks the Cloudinary asset id so a replace or removal can delete the previous asset — deletion always happens after the new row is saved, so a failed re-upload never leaves a tenant with no logo. All three routes (PATCH /tenant/info, POST /tenant/logo, DELETE /tenant/logo) return the same profile shape.

Mobile app appearance (tenant_asset_overrides): the member PWA (discuva-member) ships a bundled default hero/backdrop image for every screen — KNOWN_ASSETS (src/tenant/constants/known-assets.constant.ts) is the fixed catalog of what can be overridden (24 keys today, e.g. login-backdrop, home-door-welcome, giving-backdrop), each mapped to the screen(s) it actually renders on in the mobile app. A church can override any of these with its own image; anything left unset silently falls back to the app’s own bundled default — that fallback resolution happens client-side in discuva-member, not here. This backend only ever knows what’s been explicitly overridden.

• GET /tenant/info’s response gained an assets: Record<assetKey, imageUrl> field — only overridden keys appear in it, never the full catalog and never a default. Bundled into the same call the member app already makes on startup rather than a second round trip.
• GET /tenant/assets/catalog (AdminGuard, CHURCH_PROFILE_WRITE) — the fixed KNOWN_ASSETS list with labels/descriptions, for the admin appearance-settings page to render without duplicating the catalog client-side.
• POST /tenant/assets/:key (AdminGuard, CHURCH_PROFILE_WRITE) — upload/replace the override for one asset key. Same upload shape as logo upload (multer, 3MB limit, image-mimetype-only, CloudinaryService.uploadBuffer, into the tenant-assets Cloudinary folder this time). :key is validated against KNOWN_ASSETS in TenantAssetService, not at the DB level, so the catalog can grow without a migration. Same “new asset saved before the old one is deleted” ordering as logo upload.
• DELETE /tenant/assets/:key (AdminGuard, CHURCH_PROFILE_WRITE) — removes the override row and the Cloudinary asset, reverting that screen to the app’s bundled default. A no-op (still 200, still deletes nothing) if no override existed for that key.

TenantAssetOverride lives in public (tenant_asset_overrides, FK to tenants.id ON DELETE CASCADE), not a per-tenant schema — this is the same category of data as Tenant.logoUrl (self-service branding a church sets once and rarely touches), not operational data needing schema isolation. One row per (tenant, assetKey), enforced with a unique constraint.

The admin-side crop tool (discuva-admin’s Appearance settings page) guides toward each asset’s actual render ratio before upload, but nothing here enforces it server-side — every one of these images renders with object-cover inside a fixed-size container in the member app, so a mismatched upload crops awkwardly rather than breaking layout.

Billing & Checkout (src/billing/)

Tenant self-service surface for the plan/subscription infrastructure described in docs/MULTI_TENANT_MIGRATION.md §4.11/§9 Phase 3 — view current plan/subscription status and initiate a Paystack or Flutterwave checkout to upgrade the plan. PlanGuard itself doesn’t depend on any of this working — a tenant can always be moved onto Pro manually via the platform-admin escape hatch (PATCH /platform/tenants/:id/plan); this module is what lets a tenant do it themselves, and pay for it. (SMS billing lives entirely outside this module now — see SMS Module above for why.)

Three payment providers, registered simultaneously (PaymentProviderRegistryService) — unlike email, where one platform-default concrete class is chosen once at boot (SMS has no platform default at all, pure BYOK — see SMS Module above), PaystackPaymentProvider, FlutterwavePaymentProvider, and KoraPaymentProvider are always available; a checkout call picks one by name (?provider=paystack/flutterwave/kora in the request body), defaulting to DEFAULT_PAYMENT_PROVIDER when unspecified. All three are platform-wide credentials, not tenant BYOK — unlike SMS/email/YouTube, these charges pay the platform (plan upgrades), so the merchant keys have to be the platform’s own, never a tenant’s. This is the platform-billing counterpart to the tenant-facing, fully-BYOK giving/tithe system (src/giving-checkout/, which also supports Kora — KoraGivingProvider — plus Stripe); the two systems share no config or code, only the same proven Korapay request/webhook-signing shape.

Currency unit mismatch between the providers, handled internally: Paystack’s Initialize Transaction takes amount in the currency’s smallest unit (kobo for NGN) — matches this codebase’s existing priceCents/amountCents convention, no conversion needed. Flutterwave’s Standard Payment and Korapay’s Initialize Charge both take the major unit (naira) — every amount is divided by 100 before being sent and multiplied back where relevant. Paystack and Flutterwave both lazily create (and persist onto Plan.billingProviderPriceId) a matching provider-side plan/payment-plan object the first time a planId is checked out against, rather than requiring one to be pre-created out of band.

Kora has no verified recurring-subscription API — a real capability gap, documented rather than papered over. Unlike Paystack (plan + Initialize Transaction) and Flutterwave (payment-plans + payment_plan), Korapay has no confirmed subscription/plan product; KoraPaymentProvider.createSubscriptionCheckout is a single charge for the plan’s price (same mechanism as createOneOffCheckout), not an auto-renewing subscription. Concretely: a tenant on Paystack/Flutterwave may be silently re-charged by the provider’s own recurring engine when their period ends (see SubscriptionLapseScheduler below); a tenant on Kora never will be — they always fall through to the normal failed-renewal flow (PAST_DUE email → grace period → downgrade) and must complete a fresh checkout to renew. KoraPaymentProvider.cancelSubscription is correspondingly a documented no-op (nothing server-side to cancel), and refund() throws rather than calling an unverified endpoint — Korapay’s real refund API shape hasn’t been confirmed against sandbox behavior the way /charges/initialize and its webhook signing have (proven first in KoraGivingProvider). Don’t set DEFAULT_PAYMENT_PROVIDER=kora without accounting for this.

BillingCheckoutSession (public.billing_checkout_sessions) is recorded at checkout-initiation time, primary- keyed by the provider’s own reference (Paystack reference / Flutterwave tx_ref) — this is the only thing a webhook payload is ever trusted for identity/amount against. CheckoutService.handleWebhookEvent() looks up this row by the reference the webhook echoes back; a reference with no matching pending row (unknown, already processed, or forged) is a safe no-op, never an error that could imply something was charged. One intent today: subscription (activates a 30-day period — see SUBSCRIPTION_PERIOD_DAYS — on Subscription, not true provider-driven recurring-billing reconciliation, deferred pending live sandbox testing). A wallet_topup intent existed pre-BYOK (funded a prepaid SmsWallet debited per SMS sent) — removed along with the wallet itself once SMS went pure BYOK (§ SMS Module); BillingCheckoutType only has SUBSCRIPTION now.

Self-serve cancel/downgrade (CheckoutService.cancelSubscription): the tenant-facing counterpart to the platform-admin escape hatch. Still within a paid period (currentPeriodEnd in the future): sets Subscription.cancelAtPeriodEnd = true and the tenant keeps their plan’s features until that date — SubscriptionLapseScheduler (below) completes the downgrade once it passes, rather than yanking access from a period they already paid for. No active period left: downgrades immediately. Best-effort calls the provider’s own cancelSubscription() first (via billingProviderSubscriptionId), but a provider API failure never blocks the local downgrade — the tenant’s stated intent to stop wins regardless. Throws 400 if the tenant has no paid subscription, or if the plan is sponsored by a parent tenant (see Branch Hierarchy below — a sponsored plan isn’t the branch’s own to cancel).

Failed-renewal safety net (SubscriptionLapseScheduler, daily 04:00, distributed-lock guarded): finds every ACTIVE subscription whose currentPeriodEnd has passed with no new charge.succeeded webhook extending it. cancelAtPeriodEnd = true (a voluntary cancellation reaching its natural end) downgrades immediately, no drama. Any other lapse is treated as a failed renewal: flips status to PAST_DUE (the “queryable payment-status field” the frontend can key a banner off — SubscriptionStatus.PAST_DUE existed as an enum value long before anything actually set it), emails the tenant’s oldest active admin, and gives a GRACE_PERIOD_DAYS (7) window before finally downgrading to Free. Known limitation, documented rather than silently accepted: this is only fully accurate once Subscription.billingProviderSubscriptionId capture is wired up (still deferred, pending live sandbox testing) — until then, a tenant whose provider auto-renewal webhook this codebase doesn’t yet recognize will also pass through PAST_DUE and eventually lapse here, even if they’re genuinely still paying. “Retrying” a failing card is the provider’s own responsibility (both Paystack and Flutterwave retry several times before giving up, well within the 7-day window) — this scheduler only reflects local state, it never re-attempts a charge itself.

Branch plan sponsorship (Subscription.sponsoredByTenantId): set when a branch’s plan was comped by its parent at invite time rather than paid independently — see Branch Hierarchy below. Deliberately excluded from PlatformAnalyticsService’s MRR calculation (no real money backs it) and blocks the branch’s own admin from self-cancelling it (that’s the parent’s call, via the invite/hierarchy relationship, not a POST /billing/cancel on a plan they don’t actually pay for).

Refunds (platform-admin only, not tenant-facing): IPaymentProvider.refund(providerReference, amountCents?) — Paystack refunds by transaction reference directly; Flutterwave requires resolving the reference to its own numeric transaction id first (GET /transactions?tx_ref=), handled internally. Kora’s refund() throws unconditionally — not implemented against a verified endpoint (see above) — so refundCheckoutSession() on a Kora-paid session fails loudly rather than silently no-op’ing; refund a Kora charge directly in the Korapay dashboard instead until this is built. CheckoutService.refundCheckoutSession() only allows refunding a completed session, marks it BillingCheckoutStatus.REFUNDED, and deliberately does not automatically downgrade a plan — that requires a product decision (does downgrading strand data created on the paid tier?) this pass doesn’t take on. A platform admin issuing a refund is expected to also apply the tenant-facing consequence manually via the existing escape hatch if warranted.

Payment Providers: deactivation has real consequences (added 2026-08, same pass as Communication/Giving Providers’ equivalents). payment_providers (PlatformPaymentProvider) gives platform admins the same list/deactivate capability over paystack/flutterwave/kora that already existed for communication and giving providers — but the blast radius is meaningfully narrower here, because unlike those two there’s no per-tenant BYOK config table: every tenant shares the platform’s own provider credentials, so there’s nothing to filter out of a tenant-facing catalog and nothing per-tenant to cache-invalidate.

• PaymentProviderRegistryService.get() — used by webhook handling (handleWebhookEvent), self-serve cancel (cancelSubscription), and refunds (refundCheckoutSession) — deliberately never checks the DB isActive flag. An already-charged or already-subscribed tenant’s in-flight lifecycle must keep working regardless of a later deactivation; rejecting a webhook for an already-completed charge would take the tenant’s money without crediting their subscription, the same reasoning GivingCheckoutService.handleWebhook already established for tithe/giving webhooks.
• PaymentProviderRegistryService.assertActive() — a new, separate method, used only by initiateSubscriptionCheckout() — resolves the same provider name then throws 400 if its payment_providers row is deactivated. This is the only place deactivation is actually enforced: starting a new subscription checkout against a deactivated provider.
• PlatformPaymentProviderService.setActive() looks up every Subscription currently on that provider (any status except CANCELED) and sends a targeted TenantBroadcastService.notifyTenants() email — worded accurately rather than reusing the Communication/Giving copy verbatim, since an existing subscriber’s recurring renewal is genuinely unaffected (it flows through the webhook path above, which never checks isActive); only starting a new checkout with that provider is blocked until it’s restored.
• No registerProvider() — unlike CommunicationProvider/GivingProvider, paystack/flutterwave/kora are hard-coded IPaymentProvider classes wired into BillingModule (PaystackPaymentProvider etc.), not arbitrary BYOK entries a platform admin can add by id/name alone. A fourth vendor needs its own provider class written and registered in PaymentProviderRegistryService first, same as it always has — the DB row is just bookkeeping for that vendor’s on/off state, not a way to add one.

Routes (AdminGuard, tenant-scoped, unless noted):

Env vars: PAYSTACK_SECRET_KEY, PAYSTACK_BASE_URL, FLUTTERWAVE_SECRET_KEY, FLUTTERWAVE_SECRET_HASH, FLUTTERWAVE_BASE_URL, DEFAULT_PAYMENT_PROVIDER, SUBSCRIPTION_PERIOD_DAYS (default 30, CheckoutService’s flat renewal period), GRACE_PERIOD_DAYS (default 7, SubscriptionLapseScheduler’s PAST_DUE window before downgrading to Free) — see Environment Variables.

Not built yet: automatic capture of Subscription.billingProviderSubscriptionId from a provider’s own subscription-lifecycle webhook (see the dunning limitation note above — this is the same underlying gap); true recurring-billing reconciliation driven by the provider’s own renewal events rather than the flat 30-day period. Billing/plan settings UI in discuva-admin (/billing) is built — plan picker, cancel/downgrade, past-due banner, plan-inheritance indicator for a sponsored branch. (SMS wallet top-up UI was removed along with the wallet itself — SMS billing is now entirely the tenant’s own vendor relationship, outside this app.)

Plan feature gating (PlanGuard) — boolean gate plus an optional numeric cap: any route decorated @RequiresPlan(PlanFeature.X) first checks Plan.features membership (unchanged boolean gate, cached under plan-features:${tenantId} for 300s) and throws 403 { code: 'PLAN_UPGRADE_REQUIRED' } if the feature isn’t included. If the feature is included and the plan additionally has a numeric limit configured for it (Plan.featureLimits, a jsonb map of PlanFeature → max lifetime uses, admin-editable via PATCH /platform/plans/:id — absent key means unlimited), the guard atomically checks-and-increments a per-tenant lifetime counter (FeatureUsageService.tryConsume, backed by public.feature_usages, one row per (tenantId, feature), a single conditional INSERT ... ON CONFLICT ... WHERE count < limit so concurrent requests can’t both slip through) and throws the same PLAN_UPGRADE_REQUIRED 403 once the cap is hit. The slot is consumed before the route handler runs (not after it succeeds) — the simplest mechanism that works for every @RequiresPlan route with zero per-feature integration code, at the accepted cost of occasionally spending a use on a request that later fails for an unrelated reason (e.g. a validation error inside the handler). Usage counts are lifetime and never reset by a plan change — upgrading past a cap and later downgrading back below it still reflects prior usage rather than granting a fresh allowance. GET /platform/plans / POST /platform/plans / PATCH /platform/plans/:id all accept featureLimits alongside the existing features array; PlatformPlanService deep-validates it (each key must be a real PlanFeature, each value a positive integer).

Internal comps/discounts (Subscription.discountType/discountValue/discountReason/discountExpiresAt): a platform-admin-only manual comp, set via PATCH /platform/tenants/:id/discount and cleared via DELETE /platform/tenants/:id/discount (both TENANTS_WRITE, both require an existing Subscription row — apply PATCH /platform/tenants/:id/plan first if the tenant has none yet). discountType is percentage (1–100, validated server-side) or fixed_amount (cents); discountExpiresAt is optional — null means permanent until explicitly removed. Deliberately never touches checkout or a payment provider — same spirit as sponsoredByTenantId above, and for the same structural reason: Paystack/Flutterwave recurring charges are driven by a provider-side Plan object keyed on Plan.billingProviderPriceId, not a per-transaction amount override, so a discount here can’t change what a provider actually auto-renews at without creating a distinct provider Plan per discount tier (out of scope for an internal comp). Its effect is bookkeeping only: PlatformAnalyticsService.mrrCents() sums each active, non-sponsored subscription’s effective (discounted) price via the shared computeEffectivePriceCents() helper (src/billing/util/discount.util.ts) rather than the raw Plan.priceCents, so reported MRR reflects comps; GET /platform/tenants also returns the four discount fields per tenant for display.

Branch Hierarchy (src/branch/)

Lets a parent church invite another church to join as a branch, and see a rollup of its branches’ member count/attendance/giving — docs/MULTI_TENANT_MIGRATION.md §11’s “local compute, pushed rollups” design, now built. A branch is a tenant like any other (own schema, own admin, own everything) — the only difference is tenants.parent_tenant_id is set.

Onboarding: parent admin POST /branch/invites (email) generates a 64-char opaque token (not a JWT — has to be looked up by value later, not decoded), emails it, and records a pending row in tenant_branch_invites (public schema — has to live there since the invited church has no tenant of its own yet, the very thing the invite exists to create). POST /signup accepts an optional branchInviteToken; SignupController resolves and validates it (pending, unexpired) before enqueueing provisioning, so a bad/expired code fails fast without creating a tenant row. TenantProvisioningProcessor only marks the invite accepted after provisioning actually succeeds (see “Async Tenant Provisioning + Onboarding State Machine” above) — a subdomain collision or any other provisioning failure leaves the invite still usable for a retry rather than burning it.

Plan sponsorship (sponsorPlan, optional on POST /branch/invites): the parent’s stated intent, carried on the invite row and resolved at signup time — BranchInviteService.resolveInvite() returns a sponsoredPlanId when sponsorPlan was true and the parent currently has a paid (non-free) subscription; a parent on Free has nothing to sponsor onto, so this silently falls back to the normal independent Free-tier signup rather than erroring. When set, TenantProvisioningService.provision() creates the branch’s Subscription directly on that plan with sponsoredByTenantId pointing at the parent — no checkout, no independent payment. See Billing & Checkout above for how sponsorship affects cancellation (blocked — it isn’t the branch’s plan to cancel) and MRR (excluded).

Rollup computation (BranchRollupScheduler, daily 03:00 church time, distributed-lock guarded): iterates every active tenant — not just ones with a parent, since a branch invited later still needs history once linked — and for each one manually enters that tenant’s CLS/transaction context (BranchRollupService.computeAndUpsertOne, same mechanism as YoutubeLiveDetectionService/PlatformTenantService.impersonateTenant) to compute:

The public tenant_rollups row is upserted outside the tenant-context block (same convention as YoutubeLiveDetectionService’s own public-row update) using the plain, non-tenant-scoped repository.

Parent-side overview (GET /branch/overview): reads only tenants WHERE parent_tenant_id = :self joined against tenant_rollups — never reaches into a branch’s schema or shard directly, no cross-tenant read path exists in this class at all to get wrong (§11.2).

Sharing consent (tenants.share_data_with_parent, tenants.share_giving_with_parent): without this, a branch’s rollup became visible to its parent the instant an invite was accepted, with no notice or opt-out. Self-service, settable only by the branch’s own admin via GET/PATCH /branch/sharing-consent — never by the parent. Gates visibility at getOverview(), not computation — computeAndUpsertOne still computes and stores every branch’s real numbers regardless (a branch’s own tenant_rollups row is its own data, useful for its own future views too); consent only controls what’s exposed to a specific parent. shareDataWithParent defaults true (being a branch structurally implies a reporting relationship — that’s the point of the feature, and the admin who accepted the invite already knows a parent relationship is being formed) and gates every stat when false (all fields null, sharingEnabled: false in the response — the parent still sees the branch exists, since they invited it, just not its numbers). shareGivingWithParent defaults false regardless of the main flag — giving specifically stays opt-in even when general sharing is on, matching how sensitive individual church finances are treated everywhere else in this codebase (dedicated TITHE_READ permission, PII-scrubbing conventions).

Un-linking (either side can end the relationship): DELETE /branch/:branchTenantId (parent-initiated — detach one of this tenant’s own branches, 404 if not actually linked to them) and POST /branch/leave (branch-initiated — the current tenant leaves its own parent, 400 if it has none). Neither side is permanently locked into a relationship it no longer wants. Both revoke a sponsored plan on the way out (revokeSponsorshipIfSponsoredBy) if the departing tenant’s Subscription.sponsoredByTenantId matches the relationship being severed — continuing free access sponsored by a parent it’s no longer affiliated with wouldn’t make sense. A subscription sponsored by some other tenant (not the one being unlinked from) is left untouched.

Linking an already-onboarded tenant as a branch (TenantBranchLinkRequest, src/branch/service/branch-link-request.service.ts): the invite flow above only covers a church that doesn’t have a tenant yet — it can’t be reused for two churches that are already separate, fully-onboarded tenants, since there’s no signup step left to attach a token to. This is a two-sided negotiation between two existing tenants instead: a would-be parent’s admin sends a request naming the target’s subdomain (POST /branch/link-requests), and nothing about either tenant changes until the target’s own admin, from inside their own tenant context, explicitly accepts or declines it (POST /branch/link-requests/:id/accept//decline) — the parent cannot accept on the target’s behalf, mirroring the same “write intent first, mutate state only on confirmed action” discipline used everywhere else BYOK/checkout-shaped flows appear in this codebase. TenantBranchLinkRequest (public schema, tenant_branch_link_requests) is the sibling control-plane table to tenant_branch_invites, keyed on targetTenantId instead of an email+token pair since the target already exists to be looked up directly.

Validation at creation time: target subdomain must resolve to a real tenant, a tenant can’t link itself (target.id === parentTenantId), the target can’t already have a parent, and only one pending request between a given parent/target pair may exist at a time. On accept, target.parentTenantId is set directly (no provisioning involved — the target tenant already exists) and, if sponsorPlan was requested and the parent currently has a paid plan, the target’s existing Subscription row is switched onto the parent’s plan (planId/status: ACTIVE/cancelAtPeriodEnd: false/sponsoredByTenantId) — same fallback as BranchInviteService.resolveInvite if the parent is on Free (silently skipped, not an error, since sponsorPlan was only ever a request). Both sides get a best-effort email notification (target on request creation, parent on accept/decline) via the same manually-entered tenant-context pattern SubscriptionLapseScheduler.findAdminEmail already uses (looks up the tenant’s oldest active Admin, ordered by createdAt) — reused here through the shared runInTenantContext helper rather than duplicated inline, since the recipient’s admin row lives in a schema this service has no ambient CLS context for.

A parent can have any number of branches — getOverview()/listOutgoing() are both plain unbounded WHERE parentTenantId = :self queries, and nothing in this feature restricts branch count.

GET /branch/link-requests/outgoing//incoming return BranchLinkRequestView, not the raw entity — the entity only stores parentTenantId/targetTenantId UUIDs, so both list reads batch-fetch the referenced Tenant rows (one IN query per list call) and enrich each row with parentTenantName/targetTenantName/targetTenantSubdomain before returning, the same way BranchInviteService’s invites are already human-readable via the invite’s own email column.

Un-linking (either side can end the relationship): DELETE /branch/:branchTenantId (parent-initiated — detach one of this tenant’s own branches, 404 if not actually linked to them) and POST /branch/leave (branch-initiated — the current tenant leaves its own parent, 400 if it has none). Neither side is permanently locked into a relationship it no longer wants. Both revoke a sponsored plan on the way out (revokeSponsorshipIfSponsoredBy) if the departing tenant’s Subscription.sponsoredByTenantId matches the relationship being severed — continuing free access sponsored by a parent it’s no longer affiliated with wouldn’t make sense. A subscription sponsored by some other tenant (not the one being unlinked from) is left untouched. This applies identically regardless of whether the branch was linked via invite or via a link request — unlinkBranch/ leaveParent only look at Tenant.parentTenantId/Subscription.sponsoredByTenantId, not how the link was formed.

Routes (AdminGuard, tenant-scoped):

Branch hierarchy UI is built in discuva-admin (/branch-hierarchy) — invite-sending, branches overview with unlink, link-request sending/incoming-review, and a “this church” section showing sharing consent toggles + leave-parent, only shown when parentTenantId is actually set (see GET /branch/sharing-consent above). Multi-level hierarchy (branch-of-a-branch) is representable with zero further schema change (parent_tenant_id is self-referencing) but only flat parent → branch is exercised by anything built so far.

Forms (src/forms/)

Admin-built dynamic forms — not tied to any one use case (events, surveys, sign-ups all reuse the same builder). A form has a visibility of MEMBERS or PUBLIC, an optional link to an Event, and an ordered list of fields (TEXT, NUMBER, EMAIL, PHONE, TEXTAREA, DATE, DROPDOWN, CHECKBOX — the latter two carry an options array). A PUBLIC form is fillable with no login at all — the whole point of making it public — while MEMBERS forms require an authenticated member/worker token.

Auto-fill: a field can carry an autoFillKey (FIRST_NAME/LAST_NAME/EMAIL/PHONE_NUMBER) — the member-facing “get form for filling” endpoint resolves these against the logged-in member’s own profile and returns them as suggestedValues alongside the field definitions, so the frontend can pre-fill without needing its own copy of the mapping logic. Never applies to public/anonymous fills — there’s no member to infer from.

Submissions are keyed by field id inside a jsonb blob (FormSubmission.answers: Record<fieldId, value>), not a normalized per-answer table — editing or removing a field later never requires migrating past submissions; a removed field just leaves a harmless orphaned key behind in old submissions’ JSON, still readable/exportable.

Field diff-sync on update: PATCH /forms/:id’s fields array is diffed against the form’s existing fields — an incoming field with an id updates that row in place (keeping the id stable so existing submissions’ answer keys stay meaningful), one without an id is a new field, and an existing row missing from the incoming array is deleted. Omitting fields entirely from the PATCH body leaves them untouched.

Answer validation happens server-side against the form’s actual field definitions, not via a fixed DTO shape (SubmitFormDto.answers is just Record<string, unknown> — the schema is per-form, not knowable at compile time): required fields must be present and non-empty, and DROPDOWN/CHECKBOX values must be one of the field’s configured options.

forms is a toggleable module (KNOWN_MODULES, ModuleEnabledGuard) like most feature modules in this app — disabling it 403s all three controllers, including the public one.

Analytics (GET /forms/:id/analytics, a Google-Forms-style summary, not raw rows): computed in-memory per field from every submission’s answers[fieldId], shaped by that field’s type — DROPDOWN/CHECKBOX get a per-option {count, percentage} breakdown (CHECKBOX counts every selected value, since one submission can pick several options); NUMBER gets {average, min, max}; every other type (TEXT, EMAIL, PHONE, TEXTAREA, DATE) gets up to the 20 most recent non-blank answers as sampleAnswers, since there’s no meaningful aggregate for free text. Blank/null/undefined answers are excluded from responseCount and every computation — a field added after some submissions already exist doesn’t drag its stats toward zero.

Social Media Module (src/social-media/)

Central, tenant-scoped connector framework for cross-posting to a church’s social accounts from one compose box — currently the architecture only: no platform has live OAuth wired in yet, deliberately. Every account starts (and stays) isConnected: false, and every publish attempt against it fails honestly rather than pretending to succeed — see “Why no live platforms yet” below.

Entities:

• SocialAccount (social_accounts) — platform (SocialPlatform: FACEBOOK/INSTAGRAM/X/YOUTUBE/TIKTOK), displayName, externalAccountId (nullable — populated once a real OAuth flow exists to produce one), isConnected (always false today), connectedAt/connectedBy (nullable, for when connecting becomes real).
• SocialPost (social_posts) — content, optional imageUrl, status (SocialPostStatus: DRAFT → PUBLISHING → PUBLISHED/PARTIALLY_PUBLISHED/FAILED), createdBy (nullable FK → admins, SET NULL), publishedAt.
• SocialPostTarget (social_post_targets) — one row per (post, account) pair, so a single post’s per-platform outcome is tracked independently rather than collapsed into one post-level status: status (SocialPostTargetStatus: PENDING/SUCCESS/FAILED), errorMessage, publishedAt.

The publisher extension point (publisher/social-platform-publisher.interface.ts): SocialPlatformPublisher is a one-method interface (publish(account, post): Promise<{success, error?, externalPostId?}>). Every platform resolves to NotConnectedPublisher via SocialPublisherRegistry today, which always returns {success: false, error: "<PLATFORM> isn't connected yet — ..."}. Wiring in a real platform later (Meta Graph API, X API, etc.) means implementing this interface once and swapping that platform’s entry in the registry’s map — SocialPostService and the controller never change.

Why no live platforms yet: each platform is a separate OAuth app registration, a different API surface, and in X’s case a paid API tier — a real scope decision, not a technical default. This session shipped the full compose → target-selection → publish-attempt → per-target-result UX so it’s ready to point at real credentials the moment that’s decided, without ever telling an admin a post went out when it didn’t.

Publish semantics (SocialPostService.publish): every target is attempted independently — one platform failing never blocks the others. The post’s overall status is derived from how many targets actually succeeded: FAILED if none did, PUBLISHED if all did, PARTIALLY_PUBLISHED otherwise. publishedAt on the post is set whenever at least one target succeeded.

Deleting a post is only allowed while DRAFT or fully FAILED — a PUBLISHED/PARTIALLY_PUBLISHED/ PUBLISHING post’s target history is kept, not deletable, since it’s the record of what was actually attempted.

social_media is a toggleable module (KNOWN_MODULES, ModuleEnabledGuard). New social_media:read/ social_media:write permissions, backfilled onto existing SuperAdmin roles by GrantSocialMediaPermissions1791504000000 (same class of fix as GrantFormsPermissions — a brand-new permission is only auto-granted to a SuperAdmin role at the moment that role is created).

Utility Module

Shared infrastructure used across the entire application.

Bull Board (queue dashboard): Mounted at GET /queues on the NestJS HTTP server. Provides a standalone web UI showing all six queues (email, push-notifications, follow-up, tithe, finance-reconciliation, audit-log) with pending/active/completed/failed job counts and per-job retry controls. Protected by HTTP Basic Auth (BULL_BOARD_USER / BULL_BOARD_PASSWORD env vars). If either env var is absent the dashboard is not mounted. Registered before Helmet so the /queues path is exempt from the strict Content Security Policy.

Email queue (EmailQueueService + EmailProcessor): All outbound email goes through a Bull queue backed by Redis. EmailQueueService.queueEmailWithTemplate() compiles the HTML template using Handlebars and adds a job to the email queue. The platform-wide default email provider is resolved at startup from EMAIL_PROVIDER and injected via EMAIL_PROVIDER_TOKEN; per-send, EmailProcessor may instead resolve a tenant’s own BYOK provider — see “Email BYOK send path” under Communication Providers above. Five providers are available — see the table under Communication Providers above — all accepting optional per-call BYOK credentials. Bull handles retries automatically — 5 attempts, 5-second fixed backoff. On success or permanent failure, a row is written to email_logs with the provider field set to whichever provider actually processed that specific job.

Per-tenant branding (church_name/church_address/logo_url/support_email): resolved fresh per email by EmailQueueService.resolveBrandingData(), not read once at boot — the HTML is fully rendered before the job is queued, so this happens at enqueue time via cls.get('tenantId') → Tenant row lookup, cached under tenant-branding:${tenantId} (CACHE_TTL_REFERENCE_SECONDS, same TTL/pattern as PlanGuard’s plan-features:${tenantId} cache). Any write to a tenant’s name/logo/tagline/address (PATCH /tenant/info, POST/DELETE /tenant/logo, platform-admin’s PATCH /platform/tenants/:id) must invalidate this same key or emails keep stale branding for up to the TTL — all four call sites already do. A tenant field left unset (null) falls back to that one field’s CHURCH_NAME/CHURCH_ADDRESS/LOGO_URL env default, not the whole record — except support_email, which has no env fallback at all (empty string when unset) since a wrong/generic contact address would be actively misleading, not just generic; the 43 member/worker-facing templates that reference it gate the line behind {{#if support_email}} so it’s simply omitted rather than showing nothing useful. product_name always comes from PRODUCT_NAME (the SaaS product name) regardless of tenant — it’s platform-wide, not per-church. Bug fixed (2026-08-04): five templates (tithe-proof-{confirmed,declined,submitted}, pledge-contribution-{confirmed,declined}) had a hardcoded external logo URL instead of {{logo_url}} — every tenant’s emails from those five showed the same wrong logo, not their own. annual-giving-statement.html had no logo image at all. Both fixed; all 61 templates now reference {{logo_url}}. Formerly a known gap, now fixed: every @Cron scheduler in the codebase that touches tenant-scoped data (FollowUpScheduler included) now wraps its per-run body in forEachActiveTenant() (src/tenant/utility/for-each-active-tenant.ts), which fetches every active Tenant and re-enters that tenant’s CLS/SET LOCAL search_path context (via the existing runInTenantContext() helper) once per tenant before running the body — so branding, currency, and every other tenant-scoped lookup inside a scheduled job now resolves correctly per tenant instead of falling back to env defaults or reading the wrong schema. One tenant’s failure is caught and logged per-tenant so it doesn’t stop the rest of the batch. Only YoutubeSubscriptionScheduler (genuinely control-plane data) and SubscriptionLapseScheduler’s top-level query (also control-plane) are exempt.

Tenant-aware login URLs (login_url/admin_login_url, added 2026-08-04, admin_login_url mechanism changed 2026-08 — Phase 9l): LOGIN_URL/ADMIN_LOGIN_URL are configured as bare base URLs — every caller used to read them straight from ConfigService and pass the bare value into a template, which meant every tenant’s login links pointed at the same non-tenant-scoped host. resolveBrandingData() auto-injects both into every email, but the two now use different rewriting mechanisms, not the same one:

• login_url (discuva-member — a real per-tenant wildcard): buildTenantUrl() (src/tenant/utility/tenant-url.ts) inserts the subdomain as the leftmost host label — https://discuva.org/login → https://church-alpha.discuva.org/login.
• admin_login_url (discuva-admin — a single fixed host, no wildcard): buildAdminUrl() (same file) instead adds the subdomain as a ?subdomain= query param, since there’s no per-tenant host to prepend it onto anymore — https://admin.discuva.org/login → https://admin.discuva.org/login?subdomain=church-alpha. discuva-admin’s login/set-password forms read this param to pre-fill their “Church Subdomain” field.

All ~17 call sites that used to compute these themselves (AuthService, AdminService, MemberService, MemberImportService, IncidentReportService, and four schedulers) were simplified to rely on the auto-injected value instead — a call site should never read LOGIN_URL/ADMIN_LOGIN_URL from ConfigService directly. The one exception is AuthService.sendSessionSecurityAlert(), which has to pick between the two based on which surface (member/admin) a session belongs to — it calls UtilityService.resolveTenantLoginUrl('member' | 'admin') (delegates to EmailQueueService.resolveTenantUrl(), which internally branches to buildTenantUrl/buildAdminUrl the same way resolveBrandingData() does) directly instead. TenantProvisioningService.sendWelcomeEmail()'s set-password link is a separate case again — it builds its URL from the Tenant object already in hand (buildAdminUrl(ADMIN_LOGIN_URL, '/set-password', { email, otp, subdomain: tenant.subdomain })) rather than through CLS, since it can run from a Bull job or a synchronous platform-admin call with no tenant CLS context active; the path argument replaces ADMIN_LOGIN_URL’s own path rather than appending onto it, which also incidentally fixed a pre-existing /login/set-password double-path bug the old string-concatenation version had. PLATFORM_LOGIN_URL is deliberately untouched — platform admins aren’t tied to any tenant.

Domain map (discuva.org)

Only one DNS zone needs wildcard coverage — *.discuva.org, and only for discuva-member’s own hosting, not for any traffic bound for the API. admin.discuva.org and api.discuva.org are both plain, single DNS records, and neither needs a router in front of it splitting by path — a design an earlier draft of this table used to describe, which existed only to work around discuva-admin and discuva-member both needing to reach the API without a subdomain of their own to carry a tenant on. LOGIN_URL should be configured against the discuva.org zone; ADMIN_LOGIN_URL against admin.discuva.org (no longer the discuva.org zone — the admin app moved to its own dedicated host).

Email category gating: queueEmail* methods accept an optional category?: EmailCategory argument. If no category is supplied the email always sends (used for security-critical auth emails: OTP, password reset, account locked, etc.). Optional categories are gated by boolean config flags (EMAIL_*_ENABLED); setting a flag to false suppresses that category without touching any call sites. Current categories:

Template files live in src/utility/templates/*.html and use {{variable}} for simple substitution, {{#if}} for conditionals, and {{#each}} for loops. Values are HTML-escaped automatically; use {{{variable}}} only for intentional raw HTML.

Cloudinary (CloudinaryService): Streams file uploads to Cloudinary via upload_stream with resource_type: 'auto'. Used for finance request attachments, payment proofs, and tithe payment proofs. uploadBuffer(buffer, folder, filename?) returns {secureUrl, publicId, resourceType} — callers must persist publicId and resourceType so that assets can be deleted without re-parsing the URL. deleteByPublicId(publicId, resourceType) destroys the asset using the stored values (replaces the old deleteByUrl which hardcoded resource_type: 'raw'). The service validates all three credentials on module init and throws if any are missing. Credentials are read from CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, and CLOUDINARY_API_SECRET.

Cache (CacheService): A Redis-backed key-value cache. All read operations (get) are awaited — the result is needed before the request can continue. Write operations (set, del) are fire-and-forget for non-critical data (cache population after a DB fetch, cache invalidation on mutations) — if the Redis write is lost, the worst case is a cache miss on the next request, which falls through to the database. Rate-limit reads are always awaited; rate-limit counter clears and increments are fire-and-forget.

Caching strategy by data type:

Birthday Module

Automatically greets members on their birthday with an email and a congregation-wide announcement. Other members can send personal wishes that persist permanently in the member’s birthday book.

Cron: Runs daily at 6 AM. Queries all active members whose birthMonth and birthDay match today and whose birthdayGreetedYear is not the current year, then for each member (in an isolated try/catch):

• Creates an ALL-audience announcement with expiresAt = 23:59:59 tonight
• Updates birthdayGreetedYear to the current year (only after the announcement saves)
• Sends the birthday email (fire-and-forget via email queue)

Resilience: BirthdayService implements OnApplicationBootstrap. On startup, if the hour is ≥ 6, it fires triggerBirthdayGreetings() as a background task (fire-and-forget, guarded by a separate lock:birthday-catchup Redis lock). This recovers greetings missed because the app was down at 6 AM — the birthdayGreetedYear field prevents re-sending to members already greeted. Per-member isolation means one member’s failure never blocks the rest.

birthdayGreetedYear: Integer column (smallint) on the Member entity. Null for members who have never been greeted. Set to the current year after a successful greeting. The cron and catch-up both filter WHERE birthdayGreetedYear IS NULL OR birthdayGreetedYear != currentYear to skip already-greeted members.

Wish wall: Wishes persist in birthday_wishes regardless of announcement expiry. Rate-limited to WISH_DAILY_LIMIT wishes per sender per day (default: 20). Input is DOMPurify-sanitized.

Fields returned by /birthday/upcoming (admin-only): id, firstname, lastname, email, phoneNumber, birthMonth, birthDay, birthYear. birthYear is nullable — members aren’t required to disclose it, so the endpoint only ever uses birthMonth/birthDay (recurring, year-independent) to determine “is today/upcoming a birthday”; birthYear is included purely so callers can render a full date when it’s known, falling back to a day+month-only display when it’s not.

Fields returned by /birthday/today (member-facing, BirthdayCelebrant): id, firstname, lastname, birthMonth, birthDay, birthYear, role, departmentName, pastorType, alreadyWishedByMe, photoUrl. Deliberately does not include email/phoneNumber — those are fine for the admin-only /birthday/upcoming view but not for a response every member can call. Same-named celebrants are disambiguated instead via role/departmentName (from workerProfile.department, loaded via the workerProfile and workerProfile.department relations), pastorType (from the pastor relation), and now photoUrl (from Member.photoUrl — see Member Module) — the mobile UI shows the photo when set, falling back to initials.

alreadyWishedByMe on /birthday/today: computed per request from the caller’s own JWT identity (not present on /birthday/upcoming, which is admin-only and has no “sender” concept) — true when the calling member already has a BirthdayWish row for that recipient this calendar year. sendWish() already enforced one-wish-per-sender-per-recipient-per-year at the DB level (@Unique(['recipient', 'sender', 'year']) on BirthdayWish) and rejected a second attempt with 400 — this field just surfaces that same state proactively on load, computed via a single extra query (BirthdayWish.find({ sender, year, recipient: In(todaysBirthdayIds) })) rather than the client only discovering it reactively after a failed second send.

Routes prefix: /birthday

Membership Anniversary Module

Background-only (no controller/routes) — automated congratulatory announcement + email when a member reaches a join-date anniversary, keyed off Member.dateJoinedChurch rather than createdAt (a member’s system-account creation date can differ from their actual join date, e.g. for admin-backfilled historical records). Structurally a clone of the Birthday Module’s mechanics rather than a new pattern: same lock-key/catch-up/daily-cron shape (@Cron('0 6 * * *'), onApplicationBootstrap catch-up for missed runs, Redis lock to prevent double-sends across instances), same memberGreetedYear-style dedup marker (Member.anniversaryGreetedYear, mirrors birthdayGreetedYear). Differs from Birthday in one way: greeting delivery goes through AnnouncementService.createSystemAnnouncement() (ALL-audience, push-notifies automatically) rather than Birthday’s older direct-repository-insert pattern, which predates that helper and doesn’t push-notify.

Eligibility: ACTIVE members with a non-null dateJoinedChurch whose join month/day matches today, excluding the join year itself (a member who joined today this year has “0 years,” not an anniversary), and not already greeted this calendar year.

Email: membership-anniversary template, EmailCategory.MEMBERSHIP_ANNIVERSARY (togglable via EMAIL_MEMBERSHIP_ANNIVERSARY_ENABLED, default true, same convention as every other email category).

Audit: MEMBERSHIP_ANNIVERSARY_GREETED per member greeted (metadata: { years }).

Notes Module

Pastoral records of significant events (child naming, dedication, marriage, baptism — “rites of passage”). Admin-only write/read surface. Stored as typed JSON detail objects.

Note types: child_naming, child_dedication, marriage, baptism

Optional member link: every note type accepts an optional memberId on create/update, stored as a real FK (Note.member, nullable, SET NULL) separate from the JSON details blob — not part of any single type’s shape, since linking to a member is a cross-cutting concern, not detail data. Most naming/dedication records are for someone not yet in the system (e.g. a newborn) so this stays optional; when set, the record becomes visible on that member’s own profile via GET members/me/milestones (JwtAuthGuard, own data only, no admin permission needed). Passing memberId: null on update explicitly unlinks a note.

Routes prefix: /notes, /notes-analytics, /members/me/milestones

Dashboard Module

Aggregated data endpoints per role. Does not store data — assembles from other services.

Routes prefix: /dashboard

Sunday School Module

Manages permanent Sunday School classes, class membership, and session-based attendance. Classes have no graduation — members stay assigned indefinitely. Both teachers and enrolled students can mark attendance, but self-mark requires that a staff member has opened the window on the session.

Key flows:

• Admin or SS-dept worker creates a class and assigns a teacher (optional).
• Members are assigned to a class via the members sub-resource. Assignments are permanent until explicitly removed.
• A session is created per class per date. Staff open a timed self-mark window via PATCH /sessions/:id/open (body: { closesInMinutes: 5–480 }); members may self-mark only while selfMarkClosesAt is non-null and in the future. Staff can close the window early via PATCH /sessions/:id/close. No cron job required — the window expires automatically at query time.
• Bulk marking is used by teachers/staff; self-mark (POST /sunday-school/sessions/:id/checkin) is used by individual members.

Lesson material (SundaySchoolSession.documentUrl): optional link to that date’s lesson material (Google Drive, PDF link, etc.) — validated as a URL (@IsUrl()), settable only at session creation (POST .../sessions), same as the pre-existing notes field — neither has an update-after-creation route. Set via either the worker/teacher controller (mobile) or the admin controller; both share CreateSundaySchoolSessionDto. Surfaced as “View Lesson Material” on the teacher’s roster panel (discuva-member mobile) and via a small link icon in the admin sessions table.

Routes prefix: /sunday-school (worker/member routes) and /admin/sunday-school (admin routes)

Admin controller (/admin/sunday-school): All routes require AdminGuard. Provides the same class and session management as the worker controller but bypasses the requireSundaySchoolAuth check so that admins can manage any class regardless of department or teacher assignment.

Tithe Module

Enables the finance team to manage bank accounts, upload Excel tithe payment sheets, and review member proof submissions. Members can view their own records, request PDF statements, and submit proof of offline payments.

Account management: The finance team maintains a list of tithe bank accounts (TitheAccount) — one per physical bank account. Each account has its own currency (ISO 4217), enabling the church to accept NGN, USD, and any other currency simultaneously. Members and workers can browse active accounts at GET /tithes/accounts. Admins manage accounts via:

Account summary (GET /admin/tithes/accounts/:id/summary): Accepts optional fromMonth / toMonth (YYYY-MM) query params and returns:

{
  "account": { "...": "TitheAccount fields" },
  "fromMonth": "2026-01",
  "toMonth": "2026-06",
  "bulkTotal": 500000,
  "bulkCount": 45,
  "proofTotal": 75000,
  "proofCount": 8,
  "grandTotal": 575000
}

bulkTotal/bulkCount aggregate confirmed TitheRecord rows whose batch is linked to this account. proofTotal/proofCount aggregate CONFIRMED TithePaymentProof rows linked directly to this account.

Upload flow:

1. Finance admin selects a TitheAccount and uploads .xlsx via POST /admin/tithes/upload (multipart, field name file; body field titheAccountId).
2. Service validates that the account exists and is active, validates required columns (Email, Amount, Payment Date), and returns 400 immediately for invalid input.
3. A TitheUploadBatch record is created (linked to the account, with parsed rows stored as JSONB for safe requeue) and a Bull job (tithe queue, process-batch job) is dispatched with attempts: 3, removeOnFail: false.
4. The processor runs asynchronously inside a database transaction: matches each row to a member by email (case-insensitive), creates TitheRecord for matches, TitheUnmatchedRecord for no-match rows, and TitheDisputeRecord for rows that duplicate an existing record by (memberId, paymentDate, amount). The transaction ensures idempotent retries — a mid-batch failure rolls back all inserts so the next attempt starts from a clean slate.

Failed batch requeue: If a batch reaches FAILED status, a finance admin can requeue it via POST /admin/tithes/batches/:id/requeue. The stored rows JSONB field is used to reconstruct the job without re-uploading the file.

Excel template: Three-sheet workbook — Tithe Template (headers only), Instructions, Sample. Served at GET /admin/tithes/template.

Admin records list: GET /admin/tithes/records returns all confirmed tithe records (paginated, FINANCE_READ). Supports the following query params:

GET /admin/tithes/records/download accepts the same filters (no pagination) and returns an .xlsx file with columns: Member Name, Email, Account (bank name), Currency, Amount, Payment Date, Sender Bank, Reference.

Member visibility: Members view their own tithes at GET /tithes/me and request a PDF statement emailed to them at POST /tithes/me/statement/send (TitheService.emailTitheStatement — renamed from /tithes/me/download, which never downloaded anything; it always emailed a PDF). Optional query params fromMonth and toMonth (format YYYY-MM) filter the records included in the statement and display a period range in the PDF (e.g. ?fromMonth=2026-01&toMonth=2026-06). If only one bound is supplied the other is open-ended. Returns { message, recordCount } (200 OK) — previously returned 204 No Content, which meant the frontend’s success message could never actually render since HTTP clients discard the body of a 204 regardless of what the server sends. The email body itself (not just the attached PDF) also states the period in prose (formatStatementPeriod() — “January 2026 – June 2026” / “March 2026 onwards” / “Up to June 2026”) and the record count, falling back to “all N tithe records on file” when no range was requested, so the email is accurate on its own without needing to open the PDF.

Tithe payment proof: Members and workers submit proof of an offline tithe payment via POST /tithes/proof (multipart, field: file, max 2 MB; body field titheAccountId — the account they paid into). The file is uploaded to Cloudinary and a TithePaymentProof record is created with status PENDING and expiresAt set to TITHE_PROOF_EXPIRY_DAYS days from submission (default 90). Finance team admins review proofs at GET /admin/tithes/proofs and can CONFIRM or DECLINE each one. Confirming or declining triggers an email to the member that includes the bank name and account-level currency. A daily cron at 03:00 (church-local time, see Timezone) (with distributed Redis lock lock:tithe-proof-cleanup) finds all expired proofs (expiresAt ≤ now), deletes each file from Cloudinary using the stored publicId + resourceType, and removes the DB rows.

Routes prefix (admin): /admin/tithes
Routes prefix (member): /tithes

Finance Module

Full double-entry accounting system for the church. All financial data is fund-scoped (RESTRICTED / UNRESTRICTED). Every posted entry has balanced debit and credit lines; the balance is enforced at the service layer before posting, and a DB-level CHECK (current_balance >= -0.01) on finance_accounts is a last-resort safety net.

Core concepts:

Race condition protection:

• SELECT FOR UPDATE (pessimistic locking) on finance_accounts rows during approval and void operations — prevents concurrent writes from losing updates.
• Unique idempotency_key column on finance_journal_entries — duplicate submissions return 409 Conflict.
• CHECK (current_balance >= -0.01) DB constraint — last-resort guard.

Void / reversal pattern: Voiding a posted entry does NOT delete it. A new reversing entry (equal and opposite lines) is created with entryType = REVERSAL and both entries remain in the ledger. The original entry status becomes VOIDED. Voiding an entry in a CLOSED accounting period throws 400 Bad Request.

Tithe virtual accounts — removed. A dedicated-bank-account-per-member giving mechanism was scaffolded (entity, stub service, webhook controller) but never implemented beyond NotImplementedException on every method, and the member app’s card was labeled “Coming Soon.” Deleted entirely rather than finished — replaced by the tenant-owned Giving Checkout flow below.

Giving Checkout (Tenant-Owned, BYOK) — src/giving-checkout/

A member pays the church directly via a hosted checkout page — Paystack, Flutterwave, Korapay, or Stripe, using the church’s own merchant credentials, never a platform account. Pure BYOK, same shape as Communication Providers: no platform default exists, so the “Give via Checkout” option is simply absent from the member app until a tenant configures and activates one provider.

Provider abstraction (src/giving-checkout/interface/giving-provider.interface.ts):

type GivingProviderCredentials = Record<string, string>; // e.g. Paystack's { secretKey }, Stripe's { secretKey, webhookSecret }

interface IGivingProvider {
  readonly providerName: string;
  createCheckoutSession(params: {
    amountCents: number; currency: string; payerEmail: string; payerName: string;
    reference: string; successUrl: string; cancelUrl: string; credentials: GivingProviderCredentials;
  }): Promise<{ checkoutUrl: string }>;
  verifyAndParseWebhook(rawBody: Buffer, signatureHeader: string, credentials: GivingProviderCredentials): NormalizedGivingEvent;
}

GivingProviderRegistryService (same shape as PaymentProviderRegistryService/SmsProviderRegistryService) holds all four vendors live simultaneously; GivingCheckoutService resolves which one to use per call from the tenant’s active TenantGivingProviderConfig.providerId. Credentials are always passed as a call parameter, never injected from ConfigService — there is no platform merchant account behind any of these.

The four providers (src/giving-checkout/provider/) —

Webhook signature verification differs per vendor: Paystack HMAC-SHA512 over the raw body (x-paystack-signature); Flutterwave a direct shared-secret string compare (verif-hash, not an HMAC); Korapay HMAC-SHA256 over just the data object, not the full envelope (x-korapay-signature); Stripe HMAC-SHA256 over ${timestamp}.${rawBody} using a signing secret distinct from the API key, header format t=…,v1=… (Stripe-Signature). Each is entirely self-verifying — none of the shared “never trust the payload” discipline below depends on which scheme a given vendor uses.

Entities — all control-plane (public, never a search_path target — same reasoning as TenantCommunicationProviderConfig/BillingCheckoutSession: the inbound webhook has no Host header/subdomain to resolve a tenant from, only a :tenantId path param, so these must be resolvable with zero tenant (schema) context):

• GivingProvider (giving_providers) — platform-wide catalog, mirrors CommunicationProvider.
• TenantGivingProviderConfig (tenant_giving_provider_configs) — one row per (tenant, provider), credentialsEncrypted (jsonb, select: false, EncryptionService AES-256-GCM — same encryption as Communication Providers), isActive. Only one provider active per tenant at a time, enforced the identical way as Communication Providers: TenantGivingProviderService.upsertConfig()/setActive() (when activating) run inside a transaction that also deactivates every other config row for that tenant.
• GivingCheckoutSession (giving_checkout_sessions) — mirrors BillingCheckoutSession exactly: primary keyed by the provider’s own reference, recorded at checkout-initiation time (before the member ever reaches the provider’s hosted page) — the webhook only ever confirms/denies a session this row already describes, never a source of truth for amount/member/tenant identity itself. memberId/titheAccountId are plain UUID columns, not FK-enforced relations — Member/TitheAccount live in the tenant’s own schema, which a public-schema table can’t foreign-key into.

Checkout initiation (GivingCheckoutService.initiateCheckout, member-facing, normal in-app request — tenant context already resolved by TenantMiddleware): resolves the tenant’s active config (cached 300s per tenant, invalidated on write — identical pattern to SmsCredentialResolverService, joined against GivingProvider and requiring provider.isActive = true too, not just the tenant’s own config row — see “Giving Providers: deactivation has real consequences” below), throws 403 GIVING_PROVIDER_NOT_CONFIGURED if none is active, looks up the member for email/name, resolves currency from the optional titheAccountId (falls back to CURRENCY_CODE), generates a giving_{uuid} reference, and calls the resolved provider. Saves a PENDING GivingCheckoutSession row before returning { checkoutUrl }.

Giving Providers: deactivation has real consequences (added 2026-08, same pass as Communication Providers’ equivalent above). PlatformGivingProviderService.setActive() (PATCH /platform/giving-providers/:id) mirrors PlatformCommunicationProviderService.setActive() exactly, minus the channel dimension:

1. TenantGivingProviderService.listProviders() excludes an inactive provider from the catalog a tenant can newly select, unless that tenant already has a config against it (kept visible — discuva-admin’s giving providers page renders one row per catalog entry, same as its communication-providers page).
2. GivingCheckoutService.resolveActiveConfig() now joins GivingProvider and requires provider.isActive = true, not just config.isActive. A deactivated provider genuinely stops accepting new checkout initiations. Deliberately not applied to handleWebhook — an in-flight checkout that already charged the member on the provider’s own side must still complete and credit the church’s TitheRecord even if the provider gets deactivated in the interim; rejecting that webhook would take the member’s money without crediting it anywhere, a worse outcome than letting one already-charged transaction finish.
3. setActive() invalidates the 300s cache immediately for every tenant with an active config against the provider (givingProviderCacheKey, extracted as a shared utility for the same reason communicationProviderCacheKey was — two places already computed the identical string independently) and emails those tenants via TenantBroadcastService.notifyTenants(), targeted at only the affected tenants.

A tenant’s own TenantGivingProviderConfig row is never touched by any of this.

Webhook handling (GivingCheckoutService.handleWebhook, POST /webhooks/giving/:tenantId/:provider, @Public(), excluded from TenantMiddleware): no CLS/tenant context exists at all when this fires — tenantId comes straight from the path param. Looks up that tenant’s own active config for :provider first (verified credentials before anything else is trusted), decrypts, resolves the IGivingProvider, and calls verifyAndParseWebhook() (throws on a bad signature). A non-charge.succeeded event marks the matching session FAILED and returns — never an error response, so the provider doesn’t retry forever. On success: row-locks the PENDING GivingCheckoutSession by the event’s own reference (idempotent against webhook redelivery — a second delivery for an already-COMPLETED session finds nothing to lock, safe no-op), flips it to COMPLETED, looks up the Tenant row for its schemaName, then runInTenantContext()s into that tenant’s own schema purely to write the resulting TitheRecord (source: PAYMENT_GATEWAY, externalReference = the session id, paymentChannel = the provider id, batch: null — same “webhook-created records have no batch” shape as reconciliation-imported rows). This is the only place SMS/email BYOK’s “resolve credentials, dispatch to the right vendor class” pattern and the tenant-context-entry pattern (normally only seen in Bull processors, via runInTenantContext) are combined in the same request.

Routes:

Both finance/giving-providers and finance/giving/checkout are gated behind @RequiresModule('tithe') — disabled entirely if a church has turned off the Tithe & Giving module.

discuva-admin’s Giving Providers page shows a read-only, copyable “Webhook URL” field per provider (inside the same Configure/Edit Credentials panel as the credential inputs) — built client-side from tenantId (now returned above) and NEXT_PUBLIC_API_URL, deliberately not getTenantApiBaseUrl()'s subdomain-prefixed variant, since the webhook route itself has no subdomain to resolve a tenant from.

Platform-admin visibility (PlatformGivingProviderService, PlatformAnalyticsService.getGiving): the platform operator’s own “full overview” across every tenant, mirroring Communication Providers’ and Billing’s existing platform-support surfaces —