# SMS Platform Architecture Review ## Scope This review compares the SMS platform in this Laravel repository against the attached Evergent-style reference architecture. Status legend: - `Existing` = implemented in this repo - `Partial` = only partly implemented, admin-only, or configuration-only - `External` = clearly owned by another service or application - `Missing` = not found in this repo ## Executive Summary The SMS platform already has a strong admin and operations core: - Multi-tenant admin console with module-based access control - Customer management and Subscriber 360 - Product, package, subscription upgrade, billing, invoicing, refunds, and dunning - Support desk and Zoho Desk integration - Back-office messaging for SMS, email, push, coupons, and campaigns - Reporting, lifecycle reporting, dashboarding, global search, and business analytics - AI churn prediction, AI analyst chat, audit logging, and operational monitoring The main gaps versus the Evergent reference are customer-facing runtime capabilities and downstream enterprise integrations: - No customer checkout runtime owned in this repo - No payment gateway webhook controller owned in this repo - No explicit reconciliation / settlement engine in this repo - No explicit entitlement management service - No CMS or shipping layer - No ERP, Zendesk, or data-lake connectors found here - No Braze-like marketing automation or Vertex-like external tax engine found here ## Evergent-to-SMS Mapping | Evergent reference area | SMS repo status | What exists in this repo | Notes | | --- | --- | --- | --- | | App stores / mobile storefront | `External` | Public landing page and integration wall; hosted flow configuration UI | No app-store purchase or runtime mobile/web app flow implementation was found in this repo. | | Register | `Partial` | Hosted customer flow configuration for sign-up; admin can create customer records | Customer sign-up runtime appears to be configured here but not executed here. | | Login | `Partial` | Admin login page, Sanctum token APIs, API docs/catalog for customer auth flows | Admin auth is implemented; customer login endpoints appear documented but not implemented in repo routes/controllers. | | Self care / user account | `Partial` | Hosted customer flow configuration for user account; Subscriber 360 and customer admin views | Runtime self-care frontend/API is not owned here. | | Payment checkout | `External` | Hosted checkout configuration; billing and payment analytics | Repo docs explicitly say real checkout is owned outside this Laravel app. | | Read / content consumption | `Partial` | Content watched model and activation/engagement analytics | No CMS or reader/content delivery layer found. | | Customer care | `Existing` | Support desk, ticketing, attachments, conversation history, support analytics, Zoho Desk | Strongly implemented. | | API and web services | `Existing` | Large admin API surface, reporting APIs, support APIs, dashboard APIs, token APIs | This is one of the strongest layers in the platform. | | Login / register APIs | `Partial` | API definitions catalog and public docs | Documentation exists, but customer auth endpoints are not implemented in this repo. | | Subscription APIs | `Existing` | Upgrade subscription API, product/package APIs, customer/subscription listings, reports | Public purchase lifecycle is still external. | | Payments APIs | `Partial` | Refund, recurring cancel, billing dashboards, gateway lifecycle, invoice download | Real customer checkout and payment webhook ownership is external. | | Manage APIs | `Existing` | Admin management across products, packages, tax, support, messaging, analytics, audit | Strongly implemented. | | Identity management | `Partial` | Admin auth, bearer tokens, tenant auth context, hosted flow identity-provider setting | Full customer IAM / SSO / identity runtime was not found. | | Product catalog | `Existing` | Product Admin, Package Admin, CSV upload, product action API, package pricing and gateway plan IDs | Strongly implemented. | | Billing management | `Existing` | Billing admin, invoices, gateway lifecycle, refunds, payment trends, dunning | Strongly implemented. | | Partner settlements | `External` | None in Laravel runtime; payment journey doc points settlement/reconciliation elsewhere | Settlement ownership appears outside this repo. | | Customer care | `Existing` | Support desk, customer support analytics, Zoho Desk | Strongly implemented. | | Entitlement management | `Missing` | No explicit entitlement service or runtime access-grant layer found | Subscription data exists, but entitlement management is not modeled as a first-class module. | | Cloud management | `Missing` | No cloud control-plane or infrastructure management module found | Operational monitoring exists, but not cloud resource management. | | Application management | `Existing` | System Admin, APIs & Integrations, business units, admin accounts, custom fields, hosted flows | Strong admin tooling layer. | | Multi-tenant | `Existing` | `app_id` scoping, global model scope, tenant-aware cache keys, module access filtering | Strongly implemented. | | Audit and control | `Existing` | Centralized audit pipeline, audit APIs, ClickHouse audit storage | Strongly implemented. | | Monitoring and alerts | `Existing` | Gateway health, OTP monitoring, Mandrill webhook monitoring, data freshness, GCP log queries, Telegram alerts | Strongly implemented. | | Security | `Existing` | Auth middleware, throttling, Sanctum PATs, route protection, tenant scoping | Strongly implemented for admin/API surfaces. | | Payment gateways / eWallets | `Partial` | Gateway provider/config tables, billing analytics, refund/cancel flows, integration admin page | Concrete transactional gateway logic is strongest for Razorpay, Paytm, and Justpay; broader provider list appears configurable/marketed. | | Tax engine | `Partial` | Tax admin, tax groups, regions, compliance reports, business unit mappings | Internal tax administration exists; no external Vertex-style engine integration found. | | Marketing automation | `Partial` | Mailchimp, Mandrill, campaign segments, bulk email, template analytics | Braze-like customer journey automation not found. | | Provider internal systems | `Partial` | Zoho Desk, GCP logging, GCS storage, ClickHouse, Elasticsearch | No ERP, Zendesk, or enterprise data-lake connector found in this repo. | | Batch / webhooks | `Partial` | SMS delivery callback, Mandrill webhook, queues, scheduled jobs, exports | Payment gateway webhooks are explicitly out of repo ownership. | | Fulfillment / activation | `Partial` | Activation code ingestion and product/package activation analytics | No end-to-end fulfillment service found. | | CMS | `Missing` | None found | No content management module found. | | Shipping | `Missing` | None found | Physical fulfillment/shipping is not part of this repo. | ## Confirmed Existing Platform Modules ### Channels and Admin UX - Filament admin panel under `/admin` - Public landing, docs, and demo request pages - Hosted customer flow configuration for: - general branding - pricing page - sign-up - checkout - user account - customer care ### Core business modules - Dashboard and saved dashboards - Customer management and Subscriber 360 - Customer transactions and refunds - Products and packages - Subscription upgrades - Billing, invoices, gateway lifecycle, and dunning - Support desk and support analytics - Tax administration and compliance - Coupons, voucher-related analytics hooks, and coupon conversion performance - Back-office email, SMS, and push operations ### Messaging and campaign operations - Bulk SMS dispatch with provider routing and delivery callback handling - Bulk email dispatch and template analytics - Push notification campaigns via Firebase - Campaign segmentation and audience exports - SMS provider weightage and per-tenant gateway configuration ### Reporting, analytics, and AI - Dashboard KPIs and charts - Business analytics - Lifecycle audience reports - Refund, order conversion, coupon usage, and subscription reports - Global search - AI churn prediction - AI chat analyst - Gateway lifecycle analytics - Audit analytics ### Data and platform services - PostgreSQL transactional data - ClickHouse for journeys, support, campaigns, audit, activation codes, and analytics offload - Elasticsearch acceleration with PostgreSQL fallback - Redis queues and cache - Horizon and queue-driven background jobs - GCS-backed storage for logos, editor uploads, and ticket attachments - GCP Cloud Logging integration ## Major Missing or Externalized Capabilities ### Clearly external to this repo - Customer-facing web/mobile checkout runtime - Payment gateway callback/webhook handlers - Payment reconciliation and settlement workers - Live first-purchase payment orchestration - App-store purchase lifecycle handling ### Missing from the current codebase - Explicit entitlement management service - CMS / content publishing layer - Shipping / physical fulfillment layer - ERP connector - Zendesk connector - Data lake connector - Braze-style lifecycle marketing automation - Vertex-style external tax engine connector ## Tailored SMS Architecture Diagram ```mermaid flowchart TB classDef existing fill:#dff3e4,stroke:#2e7d32,color:#0f2a17,stroke-width:1.2px; classDef partial fill:#fff4d6,stroke:#b7791f,color:#4a3411,stroke-width:1.2px; classDef external fill:#dbeafe,stroke:#2563eb,color:#102a56,stroke-width:1.2px; classDef missing fill:#fde2e1,stroke:#c62828,color:#5b1515,stroke-width:1.2px; subgraph CH["Channels / Experience"] ADMIN["Admin Console
Filament pages, resources, widgets"]:::existing PUBLIC["Public site
landing, docs, demo"]:::existing HOSTED["Hosted Customer Flows config
sign-up, checkout, user account, customer care"]:::partial APPS["Customer Web / Mobile Apps
runtime onboarding, login, checkout, self-care"]:::external end subgraph API["API / Web Services"] ADMINAPI["Admin APIs
dashboard, billing, support, reports, back office"]:::existing TOKENAPI["Auth + Bearer token APIs
Filament auth, Sanctum PATs"]:::existing PRODAPI["Product action API"]:::existing UPGAPI["Subscription upgrade API"]:::existing SMSCB["SMS delivery callback API"]:::existing CUSTAUTH["Customer auth / signup / self-care APIs"]:::external PAYWEB["Customer checkout + payment webhook APIs"]:::external end subgraph CORE["Core SMS Platform"] TENANT["Multi-tenant app context
app_id scoping"]:::existing CUSTOMER["Customer management
Subscriber 360, refunds, transactions"]:::existing PRODUCT["Product + package catalog"]:::existing SUBS["Subscription management
plans, upgrades, cancellations, renewals insight"]:::existing BILL["Billing management
invoices, dunning, gateway lifecycle"]:::existing SUPPORT["Customer care
support desk, tickets, Zoho Desk"]:::existing BACKOFFICE["Back office messaging
SMS, email, push, coupons, campaigns"]:::existing TAX["Tax + compliance admin"]:::existing IDENTITY["Identity management
admin auth strong, customer IAM partial"]:::partial ENTITLE["Entitlement management"]:::missing SETTLE["Settlement / reconciliation engine"]:::external CMS["CMS / content services"]:::missing SHIP["Shipping / physical fulfillment"]:::missing end subgraph DATA["Data / Analytics / AI"] PG["PostgreSQL
customers, orders, subscriptions, tickets"]:::existing CHDB["ClickHouse
journeys, support, audit, campaigns, activation_code"]:::existing ES["Elasticsearch
analytics and search acceleration"]:::existing REDIS["Redis + Horizon
queues, cache, async jobs"]:::existing GCS["GCS object storage
logos, editor assets, attachments"]:::existing ANALYTICS["Dashboards, reports, lifecycle reports,
business analytics, global search"]:::existing AI["AI churn + AI analyst chat
Python + LightGBM"]:::existing end subgraph INT["Integrations"] SMSP["SMS providers
Sinch, ValueFirst, Pinpoint, Karix"]:::existing EMAILP["Email providers
Mailchimp, Mandrill"]:::existing PUSHP["Push provider
Firebase FCM"]:::existing PAYP["Payment gateways
Razorpay, Paytm, Justpay admin flows;
broader provider config supported"]:::partial ZOHO["Zoho Desk"]:::existing GCPLOG["Google Cloud Logging"]:::existing APPSTORE["App stores / store billing runtime"]:::external TAXENG["External tax engine"]:::missing BRAZE["Braze-style marketing automation"]:::missing ERP["ERP / Data Lake / Zendesk"]:::missing end subgraph OPS["Operations / Governance"] ADMINTOOLS["System Admin, APIs & Integrations,
custom fields, hosted flow config"]:::existing AUDIT["Audit + control"]:::existing MON["Monitoring + alerts
gateway health, OTP, Mandrill, freshness"]:::existing SEC["Security controls
middleware, throttling, auth"]:::existing end ADMIN --> ADMINAPI PUBLIC --> HOSTED HOSTED --> APPS APPS --> CUSTAUTH APPS --> PAYWEB TOKENAPI --> ADMINAPI PRODAPI --> PRODUCT UPGAPI --> SUBS SMSCB --> BACKOFFICE ADMINAPI --> CUSTOMER ADMINAPI --> PRODUCT ADMINAPI --> SUBS ADMINAPI --> BILL ADMINAPI --> SUPPORT ADMINAPI --> BACKOFFICE ADMINAPI --> TAX ADMINAPI --> ANALYTICS ADMINAPI --> ADMINTOOLS TENANT --> CUSTOMER TENANT --> PRODUCT TENANT --> SUBS TENANT --> BILL TENANT --> SUPPORT TENANT --> BACKOFFICE TENANT --> TAX TENANT --> ANALYTICS TENANT --> ADMINTOOLS CUSTOMER --> PG PRODUCT --> PG SUBS --> PG BILL --> PG SUPPORT --> PG BACKOFFICE --> PG TAX --> PG ANALYTICS --> PG ANALYTICS --> ES ANALYTICS --> CHDB AI --> PG AI --> CHDB ADMINAPI --> REDIS ADMINTOOLS --> GCS SUPPORT --> GCS BACKOFFICE --> SMSP BACKOFFICE --> EMAILP BACKOFFICE --> PUSHP BILL --> PAYP SUPPORT --> ZOHO MON --> GCPLOG HOSTED --> CUSTAUTH HOSTED --> PAYWEB BILL --> SETTLE BILL --> PAYWEB APPSTORE --> APPS ``` ## Recommended Next Architecture Additions If the goal is to make the SMS architecture closer to the Evergent reference, the next highest-value additions would be: 1. Add the real customer auth, registration, checkout, and self-care runtime ownership to the architecture, even if those services live outside Laravel. 2. Add explicit payment webhook and reconciliation services as first-class boxes in the platform architecture. 3. Introduce an entitlement/access service if subscription state must drive downstream content/device access. 4. Decide whether ERP, data-lake, Zendesk, external tax engine, or marketing automation are real roadmap items, and add them only when there is actual ownership or integration scope.