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 /mobile/banners/serve/:slug) with contextual targeting and Redis caching (mobile-only route)
• 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 (all composite PKs)
  targeting.ts         ← campaign_targeting_rules
  (analytics.ts deleted — impression/click events and daily stats rollups now live in MongoDB, see packages/mongodb/src/schemas/banners/ and developer/banners/analytics.mdx)

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 Analytics (MongoDB, not Postgres)

Banner impression/click events and the daily stats rollup were migrated off PostgreSQL onto MongoDB — see developer/banners/analytics.mdx for the full schema, retention/TTL policy, and write-path detail. The packages/db/src/schema/banners/analytics.ts file (which defined banner_impressions/banner_clicks/banner_stats) was deleted; those 3 Postgres tables no longer exist.

4. Runtime Rules and Domain Invariants

4.1 Serving Flow (GET /mobile/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. Sort by displayOrder ASC, weight DESC.
6. Slot fill: Split primary vs fallback (isFallback) from the qualifying assignments. 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.

Banners do not store catalog-product linkage fields as serving selectors — placement, campaign, assignment, schedule, and contextual targeting are the only inputs to which banner is chosen. The typed CTA target (§4.1a) is unrelated: it only changes what the CTA link points at once a banner has already been selected.

4.1a Typed CTA Target Resolution

banners.target_kind / target_product_id / target_category_id / target_brand_id are nullable columns constrained by chk_banners_target_exactly_one (packages/db/src/schema/banners/banners.ts). The CHECK has an all-null arm — every pre-existing banner has target_kind IS NULL, so the migration adding the columns did not need a backfill — plus one arm per kind requiring its matching id, and a url arm requiring cta_url IS NOT NULL.

Migration 0033_banner_typed_target.sql wrote the CHECK with a bare target_kind = 'product' comparison. A CHECK passes on NULL, not just on TRUE — so a row with target_kind NULL and target_product_id set was accepted: the first arm evaluated FALSE, the rest evaluated NULL, and FALSE OR NULL OR NULL OR NULL OR NULL is NULL, which passes. Migration 0034_banner_target_check_null_safe.sql wraps every discriminator in coalesce(target_kind::text, '') so each arm resolves to an actual boolean. Written up as AgentWiki/reference/learnings/backend/a-check-constraint-that-accepts-null.md; the same shape was copied cleanly from special_deal_target, but that table's target_kind is NOT NULL, and copying a proven constraint does not transfer its proof once a column's nullability changes.

BannerTargetService (apps/api/src/modules/banners/shared/banner-target.service.ts) owns resolution in both directions:

• resolveWriteTarget() — admin create/update: public ids in the DTO → internal FK ids, validated against the same shape the CHECK enforces before the write reaches the database.
• resolveResponseTargetPublicIds() / resolveResponseTargetsBatch() — admin read/list: FK ids → public ids. Admin sees a soft-deleted target's id as-is; nothing is hidden from operators.
• resolveServingTargets() — customer-facing only: FK ids → current slug + public id, filtered by deletedAt IS NULL on the target table. Resolution is by slug, not a stored URL, so renaming a product does not break an existing banner's link — the next serve resolves the new slug. A soft-deleted target is absent from the resolved map; the caller (banner-serving.service.ts) then falls back to the banner's stored cta_url instead of serving a dead link.

cta_url sync happens at read time, not write time: the admin write path stores ctaUrl from the DTO as given, and banner-serving.service.ts computes resolvedCtaUrl = target ? buildTargetUrl(target) : row.ctaUrl per response, which is what keeps cta_url looking current without a backfill job.

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

Note: banner-assignment writes (BannerAssignmentsAdminService) do not invalidate any cache — assignment-level writes in this domain rely on the serving cache's 60s TTL for eventual consistency, not explicit invalidation.

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 @happy-shop/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 6 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 @happy-shop/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 @happy-shop/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.