Skip to main content

System Architecture

This document provides an overview of the SBM CRM Platform architecture, system components, and design patterns.

Architecture Overview​

The SBM CRM Platform is built on a microservices architecture, enabling scalability, maintainability, and independent deployment of services.

System Components​

Frontend Applications​

  • WeChat Mini Program - Customer-facing mobile application
  • Admin Web App - Administrative dashboard and management interface
  • PWA (Progressive Web App) - Cross-platform web application for booking and reservations

Backend Services​

  • API Gateway - Single entry point for all API requests
  • Auth Service (/auth/api) - Handles authentication, authorization, staff management, WeChat member management, and consent management
  • Point Service (/point/api) - Manages points transactions, balance, receipt verification, and point rules
  • Reward Service (/reward/api) - Handles rewards, reward codes, and reward catalogs
  • Cluster Service (/cluster/api) - Manages membership tiers, badges, badge progress, and member interests
  • Notification Service (/notification/api) - Handles in-app notifications, email templates, mail senders, and mail actions

Note: Additional services like Campaign Service, Analytics Service, and AI Service may be implemented in future phases.

Data Layer​

  • Primary Database - PostgreSQL for transactional data
  • Analytics Database - ClickHouse for analytics and reporting
  • Cache Layer - Redis for session management and caching
  • Message Queue - RabbitMQ/Kafka for asynchronous processing

External Integrations​

  • WeChat API - WeChat Official Account and Mini Program APIs
  • Payment Gateway - WeChat Pay integration
  • POS Systems - Integration with point-of-sale systems
  • CDP Platforms - Customer Data Platform integrations

Design Patterns​

Microservices Pattern​

Each service is independently deployable and scalable:

┌─────────────┐
│  API Gateway│
└──────┬──────┘
       │
   ┌───┴───┬──────────┬──────────┬──────────┐
   │       │          │          │          │
┌──▼──┐ ┌──▼──┐  ┌──▼──┐  ┌──▼──┐  ┌──▼──┐
│Auth │ │Point│  │Reward│ │Cluster│ │Notif│
│Svc  │ │Svc  │  │Svc   │ │Svc   │ │Svc  │
└──┬──┘ └──┬──┘  └──┬───┘ └──┬───┘ └──┬──┘
   │       │          │          │          │
   └───┬───┴──────────┴──────────┴──────────┘
       │
   ┌───▼───┐
   │Database│
   └───────┘

Event-Driven Architecture​

Services communicate through events for loose coupling:

  • Customer registration events
  • Purchase completion events
  • Points earned/redeemed events
  • Campaign participation events

API-First Design​

All functionality is exposed through RESTful APIs:

  • Consistent API design patterns
  • Service-based API organization (/{service}/api)
  • Standardized response format with statusCode and data wrapper
  • OpenAPI/Swagger documentation (per service)
  • Rate limiting and throttling

Technology Stack​

Backend​

  • Language: Node.js (TypeScript), Python
  • Framework: Express.js, FastAPI
  • Database: PostgreSQL, ClickHouse
  • Cache: Redis
  • Message Queue: RabbitMQ

Frontend​

  • WeChat Mini Program: WeChat Mini Program Framework
  • Admin Web App: React, TypeScript
  • State Management: Redux Toolkit

Infrastructure​

  • Containerization: Docker
  • Orchestration: Kubernetes
  • CI/CD: GitHub Actions
  • Monitoring: Prometheus, Grafana

Data Flow​

Customer Registration Flow​

1. Customer opens WeChat Mini Program
2. WeChat OAuth → Auth Service (/auth/api/members/wechat/login)
3. Create/Update Member Profile → Auth Service
4. Initialize Points Balance → Point Service (/point/api/balance/me)
5. Assign Default Tier → Cluster Service (/cluster/api/tiers/assign)
6. Send Welcome Notification → Notification Service (/notification/api/in-apps)
7. Return member data to Mini Program

Points Earning Flow​

1. Purchase completed at POS
2. POS sends event to API Gateway
3. Point Service processes transaction (/point/api/earn)
4. Calculate points based on shop/event rules (/point/api/point-rules)
5. Update member points balance
6. Check tier upgrade eligibility → Cluster Service (/cluster/api/tier-projections)
7. Trigger notification if milestone reached → Notification Service
8. Update analytics database (if Analytics Service is available)

Security Architecture​

Authentication & Authorization​

  • OAuth 2.0 / OpenID Connect
  • JWT tokens for API authentication
  • Role-based access control (RBAC)
  • API key management for service-to-service communication

Data Security​

  • Encryption at rest (AES-256)
  • Encryption in transit (TLS 1.3)
  • PII data masking
  • Audit logging for sensitive operations

Scalability Considerations​

Horizontal Scaling​

  • Stateless services enable easy horizontal scaling
  • Load balancing across service instances
  • Database read replicas for read-heavy workloads

Caching Strategy​

  • Redis for frequently accessed data
  • CDN for static assets
  • Application-level caching for computed results

Performance Optimization​

  • Database indexing and query optimization
  • Async processing for non-critical operations
  • Batch processing for analytics

Monitoring & Observability​

Logging​

  • Centralized logging with ELK stack
  • Structured logging with correlation IDs
  • Log levels: DEBUG, INFO, WARN, ERROR

Metrics​

  • Application metrics (request rate, latency, error rate)
  • Business metrics (registrations, points earned, campaigns)
  • Infrastructure metrics (CPU, memory, disk)

Tracing​

  • Distributed tracing with OpenTelemetry
  • Request flow visualization
  • Performance bottleneck identification