Kloyst Docs Index

Welcome to the documentation for the Kloyst Backend (kloyst-core).

Kloyst is an enterprise-grade, multi-tenant WhatsApp Business SaaS platform. This doc set covers the full backend architecture: contact ingestion, messaging pipeline, pricing engine, observability, security, and deployment.

---

📚 Documentation Map

🏗 Architecture

• System Design Overview — Service modes, request flow, module boundaries

🗃 Database

• Prisma Schema Reference — All models, enums, indexes, relationships
• Database Design Decisions — Migration strategy, isolation model

📥 Contact Ingestion Pipeline

• Upload Pipeline Flow — CSV/XLSX upload → scan → parse → validate → import
• Validation Engine Rules — Row-level validation, E.164, dedup logic
• Normalization & E.164 — libphonenumber, country codes, encryption

📨 Messaging

• Queue System (BullMQ) — Job queues, concurrency, retry policy
• Outbox Pattern — DB→Redis relay with FOR UPDATE SKIP LOCKED
• Webhooks — Meta webhook handling, signature validation, event routing

💰 Pricing Engine

• Pricing Engine — Rate cards, regional pricing, platform fees, quotation flow

💳 Billing

• Billing & Wallet — Credit system, transaction types, wallet debit on send

🔒 Security

• File Protection — ClamAV scan, SHA256, quarantine
• API Security — Helmet, CORS allowlist, throttling, JWT rotation

📊 Observability & Monitoring

• Metrics & Logging — Winston transports, log levels, rotation
• Monitoring Stack — Grafana + Loki + Promtail + Dozzle setup

🔁 Resilience

• Failure Handling — Dead letter queue, retry with backoff, outbox

🔗 Sequences & Flows

• Sequence Diagrams — Auth, campaign send, contact import
• Core Flows — Data flow through the system

🤝 Integrations

• Meta / WhatsApp Integration — WABA, phone numbers, template sync
• Shared WABA Dev Guide — How shared WABA accounts work

🧪 Upsert Strategy

• Contact Upsert Strategy — Merge strategies, conflict resolution

---

🗺 Deployment Architecture (Staging)

GitHub (staging branch push)
    │
Jenkins Pipeline
    ├── rsync → /srv/apps/kloyst-core/
    ├── docker build (on server, no registry)
    └── docker compose -f docker-compose.staging.yml up -d
              │
              ├── kloyst-staging-api-gateway    → 127.0.0.1:3000
              ├── kloyst-staging-webhook-worker → 127.0.0.1:3002
              ├── kloyst-staging-worker-pool    → (internal)
              ├── kloyst-staging-outbox-relay   → (internal)
              ├── kloyst-staging-postgres       → (internal)
              └── kloyst-staging-redis          → (internal)
              │
Nginx (SSL termination, basic auth)
    ├── api.staging.kloyst.com/v1/*       → :3000
    └── api.staging.kloyst.com/webhook/*  → :3002
              │
Monitoring Stack (/srv/apps/monitoring/)
    ├── Grafana  → 127.0.0.1:3003  → logs.staging.kloyst.com
    ├── Loki     → 127.0.0.1:3100  (internal)
    ├── Promtail → (internal, tails Docker + log files)
    └── Dozzle   → 127.0.0.1:8888  → dozzle.staging.kloyst.com

---

⚙️ Core Philosophy

• Never crash on partial errors — Invalid rows are rejected; valid ones continue.
• Tenant isolation is absolute — vendorId on every query. No exceptions.
• Strict normalization — All phone numbers parsed with Google's libphonenumber to E.164.
• Auditability — Every import job, chunk, and contact change is logged immutably.
• Migration safety — prisma migrate deploy in all non-local environments. Never db push.
• Secrets via Jenkins — Zero hardcoded credentials. All injected via secret file at deploy time.