Banners Module — Backend Documentation

1. Backend Scope and Boundaries

Banners backend owns:

• Admin CRUD for banners, placements, campaigns, campaign-placement links, banner assignments, and targeting rules
• Public serving API (GET /banners/serve/:slug) with contextual targeting and Redis caching
• Public event tracking API (impression + click ingestion via BullMQ)
• BullMQ event processing (RECORD_IMPRESSION, RECORD_CLICK, SYNC_SCHEDULE_STATUS, ROLLUP_STATS)
• Cron-driven schedule synchronization (minutely) and stats rollup (nightly)

Banners backend does NOT own:

• Upload/media management — banners use mediaVariants or direct URLs
• SEO metadata creation — seoId is a soft FK
• Payment or billing — campaigns have budgetTotalPaisa / budgetDailyPaisa for tracking only

2. Module Composition (Aggregate + Leaf)

BannersModule is the aggregate root (apps/api/src/modules/banners/banners.module.ts). It composes 8 leaf modules:

BannersModule re-exports all 8 leaf modules so other modules can pull in banner services if needed.

3. Data Model (Drizzle / PostgreSQL)

3.1 Schema Source of Truth

packages/db/src/schema/banners/
  index.ts             ← barrel exports
  enums.ts             ← pgEnum definitions
  banners.ts           ← banners
  placements.ts        ← placements
  campaigns.ts         ← campaigns
  assignments.ts       ← campaign_placements + banner_assignments (composite PKs)
  targeting.ts         ← campaign_targeting_rules
  analytics.ts         ← banner_impressions + banner_clicks + banner_stats

3.2 banners Table

3.3 placements Table

3.4 campaigns Table

3.5 campaign_placements (join table — composite PK)

3.6 banner_assignments (join table — composite PK)

3.7 campaign_targeting_rules

3.8 banner_impressions (append-only)

3.9 banner_clicks (append-only)

Same as banner_impressions except:

• No referrer_url column
• Adds destination_url text (the URL clicked)

3.10 banner_stats (daily rollup — overwrite semantics)

Unique index: (banner_id, placement_id, campaign_id, stat_date). PostgreSQL treats NULL as distinct in unique indexes, so ON CONFLICT DO UPDATE does not fire for null-campaign_id rows. The rollup processor filters out campaign_id IS NULL rows; serving always provides a non-null campaign_id, so analytics rows always have a non-null campaign_id.

4. Runtime Rules and Domain Invariants

4.1 Serving Flow (GET /banners/serve/:slug)

1. Placement lookup (outside cache): Query placements by slug + is_active=true. Returns 404 (PLACEMENT_NOT_FOUND) if missing.
2. Cache check: banners:serve:<slug>:<ctx_hash> (single prefix). On miss, fetch.
3. Active campaigns: Query campaigns joined to campaign_placements for the placement_id where campaigns.status='active' AND not deleted AND within time window.
4. Targeting rules: Batch-load all campaign_targeting_rules for the active campaign IDs. Group by campaignId. Evaluate AND logic.
5. Banner assignments: Load banner_assignments joined to banners. Filter by isActive, not deleted, scheduleStatus in ('evergreen','active','scheduled'), and recurrence window.
6. Slot fill: Sort by displayOrder ASC, weight DESC. Fill primary slots first up to maxBanners. If unfilled and allowPartialRender=true, fill with fallbacks ordered by fallbackPriority ASC.
7. Cache write: Store { placement, banners } with TTL.
8. Response: Add servedAt: new Date().toISOString() AFTER cache retrieval — never cached.

4.2 Schedule Filter

Applied per banner inside slot-fill:

Recurrence window (applied on top): if recurrenceWindowStart and recurrenceWindowEnd are both set, current time (HH:MM:SS) must satisfy start <= current <= end. String comparison (HH:MM:SS is lexicographically ordered).

4.3 Cache Invalidation

• SYNC_SCHEDULE_STATUS job invalidates banners:serve:* pattern via redisCacheService.invalidatePattern() when totalChanged > 0.
• Invalidation failure is caught and logged as warn (no rethrow). The 60s TTL ensures eventual consistency.
• Admin write endpoints (banners, placements, campaigns) invalidate the *:admin:list:* cache (separate prefix per resource), not the serving cache.

4.4 inArray Safety Rule

All code paths that call Drizzle's inArray(column, values) must guard against empty arrays:

if (campaignIds.length === 0) return [];
const rows = await db.select().from(banners).where(inArray(banners.campaignId, campaignIds));

Drizzle generates invalid SQL for inArray(column, []). The serving path includes this guard.

5. Caching Strategy

Context hash: 16-character hex prefix of SHA-256 of ${deviceType}|${countryCode}|${isLoggedIn}|${language}|${hourOfDay}|${dayOfWeek}|${isNewVisitor}|${referrerDomain}.

Cache utility: CacheKeyUtil.build(prefix, segments) from @/common/utils/cache-key.util (NOT @nomor/redis).

6. BullMQ Queue Architecture

Queue name: QueueName.BANNERS = "banners". Registered in apps/api/src/services/bullmq/bull.module.ts REGISTERED_QUEUES. Both BannerTrackingModule and BannersWorkersModule register this queue; NestJS BullMQ deduplicates the Redis connection.

Deduplication: producer sets jobId = correlationId on RECORD_IMPRESSION / RECORD_CLICK. The producer catches "jobid already exists" errors and silently no-ops (idempotent tracking). The scheduler sets jobId = banner-sync-<minuteKey> and jobId = banner-rollup-<statDate> to deduplicate per-minute / per-date.

7. Cron Scheduler

BannerSchedulerService implements OnModuleInit. Uses SchedulerRegistry + CronJob from the cron library (NOT @Cron() decorator — allows dynamic registration).

SYNC_SCHEDULE_STATUS runs 4 parallel updates:

• banners scheduled → active (scheduleStatus='scheduled', publishAt <= now, not expired, not deleted)
• banners → expired (scheduleStatus IN ('active','scheduled'), expiresAt < now, not deleted)
• campaigns scheduled → active (status='scheduled', startsAt <= now, not ended, not deleted)
• campaigns → ended (status IN ('active','scheduled'), endsAt < now, not deleted)

ROLLUP_STATS queries impression + click counts grouped by (banner_id, placement_id, campaign_id) for the given statDate, filtered by campaign_id IS NOT NULL (PostgreSQL unique-index limitation), and upserts with overwrite semantics: impressions = EXCLUDED.impressions, clicks = EXCLUDED.clicks, updatedAt = NOW(). Processed in batches of 100 (ROLLUP_BATCH_SIZE).

8. Error Codes

All error codes defined in apps/api/src/common/types/error-codes.ts (per-app, imported via @/common/types/error-codes).

Error throw pattern (object form):

throw new NotFoundException({ message: "Banner not found.", errorCode: ErrorCodes.BANNER_NOT_FOUND });

9. Performance Notes

• Serving endpoint is the hot path: Designed to return from Redis cache on the vast majority of requests. DB queries only on cache miss.
• Placement lookup outside cache: Intentional — provides fast 404 for invalid slugs without cache poisoning.
• 4-query serving algorithm: Placement → campaigns → targeting rules → assignments. Each query fetches all needed data in one round-trip.
• Analytics writes are async: Impression/click inserts go through BullMQ, never blocking the tracking response. The tracking endpoint returns 202 Accepted immediately.
• Stats rollup is idempotent: ON CONFLICT DO UPDATE SET impressions = EXCLUDED.impressions — re-running for the same date produces identical rows. Safe to retry failed jobs.
• Schedule sync is batched: 4 parallel UPDATE...RETURNING queries execute concurrently. Cache invalidation only fires when totalChanged > 0.
• Stats rollup batches inserts: Processes in batches of 100 rows.

10. Architecture Diagram

11. QA Checklist

• All 9 Drizzle tables have correct PK types (serial / bigserial / composite; NOT uuid for internal PKs)
• public_id uuid7 present on banners, placements, campaigns, campaign_targeting_rules
• Join tables (campaign_placements, banner_assignments) use composite PKs (no separate id column)
• Money columns use _paisa bigint suffix — no float/numeric for currency
• CacheKeyUtil.build() imported from @/common/utils/cache-key.util — NOT @nomor/redis
• servedAt added AFTER redisCacheService.getOrSet() call, never inside the callback
• All inArray() calls guarded with .length > 0 check before calling
• QueueName.BANNERS present in REGISTERED_QUEUES in bull.module.ts
• BannersModule registered in app.module.ts
• All 6 banner modules (Banners, Placements, Campaigns, Assignments, Targeting, plus BannerServing, BannerTracking, BannersWorkers) registered in default.swagger.ts
• All error codes prefixed BANNER_, PLACEMENT_, CAMPAIGN_, CAMPAIGN_PLACEMENT_, BANNER_ASSIGNMENT_, TARGETING_RULE_
• Error throw uses object form: throw new XxxException({ message, errorCode })
• Swagger decorators use positional form: @ApiResponseDto(SomeDto) (not object form)
• No console.log — all logging via new Logger(ClassName.name)
• All tests pass: pnpm --filter @nomor/api test --testPathPatterns="banners"
• Drizzle migration file generated and runs without errors

12. File Map

apps/api/src/modules/banners/
  banners.module.ts                          ← aggregate root
  admin/
    banners/                                 ← BannersAdminModule
    placements/                              ← PlacementsAdminModule
    campaigns/                               ← CampaignsAdminModule
    assignments/                             ← AssignmentsAdminModule
      (campaign-placements-admin.{controller,service}.ts)
      (banner-assignments-admin.{controller,service}.ts)
    targeting/                               ← TargetingAdminModule
  public/
    serving/                                 ← BannerServingModule
    tracking/                                ← BannerTrackingModule
  workers/                                   ← BannersWorkersModule
    (banner-events.processor.ts)
    (banner-scheduler.service.ts)
  __tests__/
    unit/
      banner-serving.service.unit.spec.ts
      banner-tracking.service.unit.spec.ts
      banner-events.processor.unit.spec.ts
      banner-scheduler.service.unit.spec.ts
    integration/
      banners-admin.integration.spec.ts
      banner-events.integration.spec.ts
    e2e/
      banner-serving.e2e.spec.ts

packages/db/src/schema/banners/
  index.ts                                   ← barrel
  enums.ts
  banners.ts
  placements.ts
  campaigns.ts
  assignments.ts
  targeting.ts
  analytics.ts

packages/jobs/src/index.ts                  ← QueueName.BANNERS + BannerJob enum + payload interfaces

13. Environment Variables

All three are added to apps/api/src/config/env.validation.ts with the defaults above. BANNER_SCHEDULE_SYNC_CRON and BANNER_STATS_ROLLUP_CRON are required (no default fallback) — service uses ConfigService.getOrThrow for them.