Skip to main content

System Architecture

The Kloyst Campaign Quotation & Cost Estimation Engine is built using NestJS, PostgreSQL, Prisma, Redis, and BullMQ. It leverages a Puppeteer Docker Sidecar for isolated, enterprise-grade PDF rendering.

🏗️ Structural Overview​

🧩 Architectural Component Mapping​

1. The Controller Layer (PricingController)​

  • Scoped strictly to route handling and input validation.
  • Extracts vendorId securely from JWT credentials via the @CurrentUser() decorator.
  • Avoids business logic; yields processing directly to the engine service.

2. The Orchestration Layer (PricingEngineService)​

  • Integrates all auxiliary services sequentially.
  • Acts as a transaction control center. If any validation fails, the process terminates before snapshot persistence to prevent database write bloat.

3. The Resolution Layer​

  • AudienceResolverService: Dynamically interprets target selections (by list, label, or saved filters) and provides deduplicated recipient sets.
  • CountryResolverService: Executes performance-optimized SQL grouping queries, sorting recipients into destination ISO country codes to determine pricing rules.

4. The Rules & Markups Layer​

  • PricingConfigService: Loads active base Meta rates per category and country calling code, employing Redis cache structures with short-lived TTLs (1 hour).
  • TierEngineService: Determines bulk discounts (applicable only to Utility and Authentication categories, following official Meta specifications).
  • PlatformFeeService: Processes percentage, flat, or hybrid markups. Automatically resolves custom enterprise overrides before returning the global default platform markup.

5. The Wallet Feasibility Layer (WalletFeasibilityService)​

  • Prevents campaign execution attempts when balance thresholds are violated.
  • Seamlessly returns walletApplicable: false for Dedicated WABA plans to accommodate Meta's direct enterprise invoicing model.

6. The Persistence & Archival Layer​

  • SnapshotService: Commits an immutable JSON representation of the configuration tables used during estimation. Ensures mathematical audit trails independent of future updates.
  • QuotationService: Registers the quotation with sequential KQ-YYYY-NNNNN formatting.

7. The Asynchronous Worker Layer (PDFGenerationWorker)​

  • Processes high-overhead HTML-to-PDF tasks out-of-band using BullMQ.
  • Establishes communication protocols with Puppeteer running in a dedicated Docker sidecar container. This mitigates memory exhaustion risks and simplifies container scale-out strategies.