Skip to main content

Kloyst Campaign Quotation & Cost Estimation Engine

Welcome to the documentation for the Kloyst Campaign Quotation & Cost Estimation Engine. This module provides highly accurate, scalable, and database-driven cost previews, wallet feasibility evaluations, and downloadable quotation PDFs for WhatsApp campaigns, completely decoupled from Meta's actual backend billing reconciliation.

📁 Directory Structure​

The documentation is organized into modular sections for readability and maintainability:

docs/pricing_engine/
├── README.md                           # This overview and quick-start guide
├── architecture/
│   └── system-architecture.md          # Multi-tenant orchestrator layout & workers
├── data-models/
│   └── schema-reference.md             # Prisma models, relationships & index strategies
├── api-design/
│   └── api-contracts.md                # Request/response DTOs & endpoints
├── estimation-logic/
│   └── estimation-pipeline.md          # Step-by-step pipeline from contacts to total
├── region-mapping/
│   └── country-resolution.md           # Grouping contacts, E.164 parsing & fallbacks
├── pricing-config/
│   └── pricing-configuration.md        # Database-driven rates, categories, and admin rules
├── platform-fees/
│   └── fee-calculation.md              # Global markups and per-tenant custom negotiation overrides
├── pricing-snapshots/
│   └── snapshot-lifecycle.md           # Immutable snapshots, reproducibility & checksums
├── quotation-engine/
│   └── quotation-lifecycle.md          # State transitions, daily expiry cron, quote numbering
├── quotation-pdf/
│   └── pdf-generation.md               # Puppeteer Docker sidecar, async BullMQ & templates
├── caching/
│   └── redis-strategy.md               # Cache keys, TTLs, write-through & invalidation
├── seed-strategy/
│   └── seed-pipeline.md                # Normalized JSON rate sheets and seeding
├── currency/
│   └── currency-foundation.md          # Multicurrency schema design preparation
└── observability/
    └── metrics-logging.md              # Drift detection, logging levels & metrics

🚀 Quick Start / Ingestion Flow​

  1. Upload Contacts: Contacts are ingested, normalized (E.164 formats, country codes parsed), and saved.
  2. Estimate Cost:
    • The vendor selects an audience (e.g., a specific tag/label, a contact list, or dynamic queries).
    • The engine checks for duplicate phone numbers, exclusions, and invalid numbers.
    • The engine resolves the destination countries, calculates pricing from active configurations, applies platform margins/overrides, and checks wallet balances.
    • An immutable pricing snapshot is frozen, a quotation is issued, and a PDF generation job is sent to BullMQ.
  3. Async PDF Generation:
    • BullMQ picks up the job.
    • The worker renders HTML using the frozen snapshot data.
    • Puppeteer (in a Docker sidecar) connects via WebSocket, renders the HTML, saves the PDF, and updates the database.
  4. Download: The vendor views the breakdown instantly and downloads the official quotation PDF once ready.