zod-backend/ALLOWANCE_SCHEDULING_SYSTEM.md

Allowance Scheduling System (Backend)

This document captures the complete allowance scheduling feature as implemented in the backend. It is intended as a long-term reference for how the system works, why it was built this way, and how to operate/extend it safely.

Goals and Scope

• Allow parents/guardians to create a recurring allowance schedule for a child.
• Credit the allowance automatically based on the schedule.
• Scale safely with multiple workers and avoid duplicate credits.
• Keep cron lightweight and offload work to RabbitMQ workers.

Non-goals in the current implementation:

• UI changes
• Analytics/reporting views
• Advanced scheduling (e.g., custom weekdays)

High-Level Flow

1. Parent creates a schedule via API.
2. Cron runs every 5 minutes and enqueues due schedules into RabbitMQ.
3. Workers consume queue messages, credit the allowance, and update the next run.
4. Idempotency is enforced in the database to prevent duplicate credits.

Data Model

Table: allowance_schedules

Purpose: Stores the schedule definition (amount, frequency, status, next run).

Key fields:

• guardian_id, junior_id: who funds and who receives.
• amount: the allowance amount.
• frequency: DAILY / WEEKLY / MONTHLY.
• status: ON / OFF.
• next_run_at, last_run_at: scheduling metadata.

Constraints:

• Unique (guardian_id, junior_id) ensures one schedule per child.

Entity: src/allowance/entities/allowance-schedule.entity.ts

Table: allowance_credits

Purpose: Audit log and idempotency guard for each credit run.

Key fields:

• schedule_id: which schedule executed.
• transaction_id: the resulting transaction (nullable).
• amount, run_at, credited_at.

Idempotency:

• Unique (schedule_id, run_at) prevents duplicates even with multiple workers.

Entity: src/allowance/entities/allowance-credit.entity.ts

Table: cron_runs

Purpose: shared audit table for all cron jobs (not just allowance).

Key fields:

• job_name: unique identifier for the cron.
• status: SUCCESS / FAILED.
• processed_count: number of schedules processed.
• error_message: failure reason.
• started_at, finished_at.

Entity: src/cron/entities/cron-run.entity.ts

API (Schedule Creation)

Endpoint:

• POST /guardians/me/allowances/:juniorId

Input DTO:

• amount (required, numeric, positive)
• frequency (required, enum)
• status (required, enum)

DTO: src/allowance/dtos/request/create-allowance-schedule.request.dto.ts

Response DTO:

• AllowanceScheduleResponseDto with schedule fields.

DTO: src/allowance/dtos/response/allowance-schedule.response.dto.ts

Business validation:

• Child must belong to guardian.
• No duplicate schedule for the same guardian+child.

Service: src/allowance/services/allowance.service.ts

Cron Producer (Queue Enqueue)

Cron job:

• Runs every 5 minutes.
• Batches schedules (cursor-based) to avoid large load.
• Enqueues each schedule to RabbitMQ.

Cron: src/cron/tasks/allowance-schedule.cron.ts

Batch behavior:

• Batch size = 100
• Uses a cursor (nextRunAt, id) for stable pagination.
• Prevents re-reading the same rows.

Locking:

• BaseCronService uses cache lock to ensure only one instance runs.
• Each cron run is logged to cron_runs with status and processed count.

Lock: src/cron/services/base-cron.service.ts

Queue Publisher

Queue publisher:

• Asserts queue + retry/DLQ exchanges.
• Enqueues jobs with message id (for traceability).

Service: src/allowance/services/allowance-queue.service.ts

Queue names:

• allowance.schedule (main)
• allowance.schedule.retry (retry with TTL)
• allowance.schedule.dlq (dead-letter queue)

Constants: src/allowance/constants/allowance-queue.constants.ts

Worker Consumer (Transfers)

Worker:

• Consumes allowance.schedule queue.
• Validates schedule is due and active.
• Creates allowance_credits record for idempotency.
• Transfers money via cardService.transferToChild.
• Updates last_run_at and next_run_at.

Worker: src/allowance/services/allowance-worker.service.ts

Transfer:

• Uses existing logic in card.service.ts for balance updates and transaction creation.

Service: src/card/services/card.service.ts

Idempotency details

1. Worker inserts allowance_credits row first.
2. Unique constraint blocks duplicates.
3. If transfer fails, the credit row is removed so the job can retry.

This makes multiple workers safe.

Retry + DLQ Strategy

Retry delay:

• Failed jobs are dead-lettered to retry queue.
• Retry queue has messageTtl = 10 minutes.
• After TTL, job is routed back to main queue.

DLQ:

• If a job fails ALLOWANCE_MAX_RETRIES times (default 5), it is routed to the DLQ.
• This prevents endless loops and allows manual inspection.

Config:

• ALLOWANCE_MAX_RETRIES (default 5)

Redis Usage

Redis is used by BaseCronService to enforce a distributed lock for the cron job. This prevents multiple backend instances from enqueuing the same schedules at the same time.

Lock behavior:

• If the lock key exists, cron exits early.
• If the lock key is absent, cron sets it with a TTL and proceeds.
• TTL ensures the lock is released even if a node crashes.

Service: src/cron/services/base-cron.service.ts

RabbitMQ Setup and Behavior

The allowance system uses RabbitMQ for asynchronous processing. Cron publishes due schedules, and workers consume them.

Exchanges and Queues

Main queue:

• allowance.schedule

Retry setup:

• Exchange: allowance.schedule.retry.exchange
• Queue: allowance.schedule.retry
• Binding key: allowance.schedule
• TTL: 10 minutes
• Dead-letter route: back to allowance.schedule

Dead-letter queue (DLQ):

• Exchange: allowance.schedule.dlq.exchange
• Queue: allowance.schedule.dlq
• Binding key: allowance.schedule

Flow Summary

1. Cron enqueues jobs to allowance.schedule.
2. Worker consumes jobs from allowance.schedule.
3. On failure, job is dead-lettered to allowance.schedule.retry.
4. After 10 minutes, it returns to allowance.schedule.
5. After max retries, worker publishes the job to allowance.schedule.dlq.

Where it is configured

• Publisher setup: src/allowance/services/allowance-queue.service.ts
• Worker consumer: src/allowance/services/allowance-worker.service.ts
• Queue constants: src/allowance/constants/allowance-queue.constants.ts

Environment Variables

• RABBITMQ_URL (required for queue/worker)
• ALLOWANCE_QUEUE_NAME (optional, defaults to allowance.schedule)
• ALLOWANCE_MAX_RETRIES (optional, defaults to 5)
• ALLOWANCE_RETRY_DELAY_MS (optional, defaults to 10 minutes)

Example .env snippet

RABBITMQ_URL=amqp://guest:guest@localhost:5672
ALLOWANCE_QUEUE_NAME=allowance.schedule
ALLOWANCE_MAX_RETRIES=5
ALLOWANCE_RETRY_DELAY_MS=600000

Operational Checklist

• Ensure Redis is running (cron locking).
• Ensure RabbitMQ is running (queue + workers).
• Start at least one worker process.
• Monitor DLQ for failures.

Manual Test Checklist

1. Create schedule:
   • POST /guardians/me/allowances/:juniorId
   • Valid amount, frequency, status.
2. Duplicate schedule:
   • Expect ALLOWANCE.ALREADY_EXISTS.
3. Cron enqueue:
   • Wait for cron interval or manually trigger.
   • Confirm messages appear in RabbitMQ.
4. Worker:
   • Ensure worker is running.
   • Verify transfers happen and allowance_credits is created.
5. Failure paths:
   • Simulate transfer failure and verify retry queue behavior.
   • Confirm DLQ after max retries.

Operational Notes

• For large volumes, scale workers horizontally.
• Keep cron lightweight; do not perform transfers in cron.
• Monitor queue depth and DLQ entries.

Known Limitations (Current)

• Only one schedule per child (guardian+junior unique).
• No custom weekdays or complex schedules.
• Retry delay is fixed at 10 minutes (can be configurable).

File Map (Quick Reference)

• API:

  • src/allowance/controllers/allowance.controller.ts
  • src/allowance/services/allowance.service.ts
  • src/allowance/dtos/request/create-allowance-schedule.request.dto.ts
  • src/allowance/dtos/response/allowance-schedule.response.dto.ts

• Cron:

  • src/cron/tasks/allowance-schedule.cron.ts
  • src/cron/services/base-cron.service.ts

• Queue/Worker:

  • src/allowance/services/allowance-queue.service.ts
  • src/allowance/services/allowance-worker.service.ts
  • src/allowance/constants/allowance-queue.constants.ts

• Repositories:

  • src/allowance/repositories/allowance-schedule.repository.ts
  • src/allowance/repositories/allowance-credit.repository.ts

• Entities:

  • src/allowance/entities/allowance-schedule.entity.ts
  • src/allowance/entities/allowance-credit.entity.ts