System Design - ThriveSend B2B2G

Version: 0.1.4 Last Updated: October 15, 2025 Status: Production

System Architecture Overview

graph TB
    subgraph "Client Layer"
        WEB[Web Browser]
        MOBILE[Mobile App Future]
    end

    subgraph "CDN & Edge"
        CF[Cloudflare CDN]
        EDGE[Edge Functions]
    end

    subgraph "Application Layer - Next.js 15"
        NEXTJS[Next.js App Router]
        SSR[Server-Side Rendering]
        API[API Routes 92 endpoints]
        MW[Middleware Auth/POPIA]
    end

    subgraph "Service Layer"
        ANALYTICS[Analytics Service]
        CAMPAIGN[Campaign Service]
        CLIENT[Client Service]
        COMPLIANCE[Compliance Service]
        TEAM[Team Service]
        CONTENT[Content Service]
        PREDICT[Predictive ML Service]
    end

    subgraph "Data Layer"
        PRISMA[Prisma ORM]
        PG[(PostgreSQL 16)]
        REDIS[(Redis Cache)]
    end

    subgraph "External Services"
        CLERK[Clerk Auth]
        RESEND[Resend Email]
        SENTRY[Sentry Monitoring]
    end

    subgraph "Storage & Logs"
        S3[Object Storage]
        LOGS[Audit Logs]
        BACKUP[Backup Storage]
    end

    WEB --> CF
    MOBILE -.-> CF
    CF --> NEXTJS
    NEXTJS --> SSR
    NEXTJS --> API
    NEXTJS --> MW

    API --> ANALYTICS
    API --> CAMPAIGN
    API --> CLIENT
    API --> COMPLIANCE
    API --> TEAM
    API --> CONTENT
    API --> PREDICT

    ANALYTICS --> PRISMA
    CAMPAIGN --> PRISMA
    CLIENT --> PRISMA
    COMPLIANCE --> PRISMA
    TEAM --> PRISMA
    CONTENT --> PRISMA
    PREDICT --> PRISMA

    PRISMA --> PG
    PRISMA --> REDIS

    MW --> CLERK
    CONTENT --> RESEND
    API --> SENTRY

    PG --> LOGS
    PG --> BACKUP
    CONTENT --> S3

    style PG fill:#e1f5fe
    style NEXTJS fill:#f3e5f5
    style CLERK fill:#e8f5e9
    style CF fill:#fff3e0

Multi-Tenant B2B2G Architecture

graph TB
    subgraph "Service Provider Organizations Tenants"
        ORG1[Organization 1<br/>Service Provider A]
        ORG2[Organization 2<br/>Service Provider B]
        ORG3[Organization 3<br/>Service Provider C]
    end

    subgraph "Organization 1 Clients"
        GOV1[Government Client 1<br/>Department of Health]
        BIZ1[Business Client 1<br/>ABC Corporation]
        GOV2[Government Client 2<br/>Municipality XYZ]
    end

    subgraph "Organization 2 Clients"
        GOV3[Government Client 3<br/>Provincial Dept]
        BIZ2[Business Client 2<br/>SME Company]
    end

    subgraph "Data Isolation"
        DB1[(Org 1 Data<br/>Complete Isolation)]
        DB2[(Org 2 Data<br/>Complete Isolation)]
        DB3[(Org 3 Data<br/>Complete Isolation)]
    end

    ORG1 --> GOV1
    ORG1 --> BIZ1
    ORG1 --> GOV2
    ORG2 --> GOV3
    ORG2 --> BIZ2

    GOV1 -.-> DB1
    BIZ1 -.-> DB1
    GOV2 -.-> DB1
    GOV3 -.-> DB2
    BIZ2 -.-> DB2
    ORG3 -.-> DB3

    style DB1 fill:#e1f5fe
    style DB2 fill:#e1f5fe
    style DB3 fill:#e1f5fe
    style GOV1 fill:#ffebee
    style GOV2 fill:#ffebee
    style GOV3 fill:#ffebee
    style BIZ1 fill:#e8f5e9
    style BIZ2 fill:#e8f5e9

Component Architecture

graph LR
    subgraph "Presentation Components"
        PAGES[Pages 14]
        LAYOUT[Layout Components]
        DASH[Dashboard Components 26]
        UI[UI Base Components 50]
    end

    subgraph "Business Logic"
        HOOKS[Custom Hooks]
        CONTEXT[React Context]
        SERVICES[Service Layer 25]
    end

    subgraph "Data Access"
        API_ROUTES[API Routes 92]
        PRISMA_CLIENT[Prisma Client]
        CACHE[Cache Layer]
    end

    PAGES --> DASH
    PAGES --> UI
    PAGES --> LAYOUT
    DASH --> HOOKS
    DASH --> CONTEXT
    HOOKS --> SERVICES
    CONTEXT --> SERVICES
    SERVICES --> API_ROUTES
    API_ROUTES --> PRISMA_CLIENT
    API_ROUTES --> CACHE
    PRISMA_CLIENT --> CACHE

    style SERVICES fill:#f3e5f5
    style API_ROUTES fill:#e1f5fe
    style PRISMA_CLIENT fill:#e8f5e9

Request Flow Architecture

sequenceDiagram
    participant U as User
    participant CF as Cloudflare
    participant NX as Next.js
    participant MW as Middleware
    participant API as API Route
    participant SVC as Service
    participant DB as Database
    participant AUDIT as Audit Log

    U->>CF: HTTP Request
    CF->>NX: Forward Request
    NX->>MW: Authentication Check
    MW->>MW: Verify Clerk JWT
    MW->>MW: Check Organization
    MW->>NX: Authorized
    NX->>API: Route to API
    API->>API: Validate Input
    API->>SVC: Call Service
    SVC->>DB: Query Data
    DB-->>SVC: Return Data
    SVC->>AUDIT: Log Action POPIA
    AUDIT-->>SVC: Logged
    SVC-->>API: Return Result
    API-->>NX: JSON Response
    NX-->>CF: HTTP Response
    CF-->>U: Display Result

    Note over AUDIT: Every data operation<br/>logged for POPIA

Deployment Architecture

graph TB
    subgraph "GitHub"
        CODE[Source Code]
        ACTIONS[GitHub Actions CI/CD]
    end

    subgraph "Production Environment"
        VERCEL[Vercel Frontend]
        RAILWAY[Railway Backend]
        PG_PROD[(PostgreSQL Production)]
        REDIS_PROD[(Redis Production)]
    end

    subgraph "Monitoring"
        SENTRY[Sentry Error Tracking]
        LOGS[Log Aggregation]
        METRICS[Performance Metrics]
    end

    subgraph "Backup & Recovery"
        PG_BACKUP[(Database Backups)]
        S3_BACKUP[Object Storage Backups]
    end

    CODE --> ACTIONS
    ACTIONS --> VERCEL
    ACTIONS --> RAILWAY

    VERCEL --> PG_PROD
    RAILWAY --> PG_PROD
    RAILWAY --> REDIS_PROD

    VERCEL --> SENTRY
    RAILWAY --> SENTRY

    PG_PROD --> LOGS
    RAILWAY --> LOGS

    PG_PROD --> PG_BACKUP
    RAILWAY --> S3_BACKUP

    PG_PROD --> METRICS
    RAILWAY --> METRICS

    style PG_PROD fill:#e1f5fe
    style VERCEL fill:#f3e5f5
    style RAILWAY fill:#e8f5e9

Security Architecture

graph TB
    subgraph "Security Layers"
        L1[Layer 1: CDN Cloudflare]
        L2[Layer 2: Auth Clerk JWT]
        L3[Layer 3: RBAC Permissions]
        L4[Layer 4: Data Row-Level Security]
        L5[Layer 5: Audit Logging]
    end

    subgraph "Security Clearance System"
        BASIC[Basic Clearance<br/>Public Data<br/>Municipal]
        ENHANCED[Enhanced Clearance<br/>Confidential Data<br/>Provincial]
        CONFIDENTIAL[Confidential Clearance<br/>Secret Data<br/>National]
    end

    subgraph "POPIA Protection"
        ENCRYPT[Encryption at Rest]
        TLS[TLS 1.3 in Transit]
        AUDIT[Complete Audit Trail]
        CONSENT[Consent Management]
        RESIDENCY[SA Data Residency]
    end

    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 --> L5

    L3 --> BASIC
    L3 --> ENHANCED
    L3 --> CONFIDENTIAL

    L5 --> ENCRYPT
    L5 --> TLS
    L5 --> AUDIT
    L5 --> CONSENT
    L5 --> RESIDENCY

    style L1 fill:#ffebee
    style L2 fill:#fff3e0
    style L3 fill:#f3e5f5
    style AUDIT fill:#e1f5fe

API Architecture

graph TB
    subgraph "API Categories 92 Total"
        ANALYTICS_API[Analytics 7]
        CAMPAIGN_API[Campaigns 13]
        CLIENT_API[Clients 7]
        COMPLIANCE_API[Compliance 4]
        CONTENT_API[Content 11]
        TEAM_API[Team 6]
        SP_API[Service Provider 9]
        OTHER_API[Other 35]
    end

    subgraph "API Middleware"
        AUTH_MW[Authentication]
        ORG_MW[Organization Check]
        RATE_MW[Rate Limiting]
        AUDIT_MW[POPIA Audit]
        VALIDATE_MW[Input Validation]
    end

    subgraph "Response Handling"
        SUCCESS[200/201 Success]
        ERROR_400[400 Bad Request]
        ERROR_401[401 Unauthorized]
        ERROR_403[403 Forbidden]
        ERROR_404[404 Not Found]
        ERROR_500[500 Server Error]
    end

    ANALYTICS_API --> AUTH_MW
    CAMPAIGN_API --> AUTH_MW
    CLIENT_API --> AUTH_MW
    COMPLIANCE_API --> AUTH_MW
    CONTENT_API --> AUTH_MW
    TEAM_API --> AUTH_MW
    SP_API --> AUTH_MW
    OTHER_API --> AUTH_MW

    AUTH_MW --> ORG_MW
    ORG_MW --> RATE_MW
    RATE_MW --> AUDIT_MW
    AUDIT_MW --> VALIDATE_MW

    VALIDATE_MW --> SUCCESS
    VALIDATE_MW --> ERROR_400
    AUTH_MW -.-> ERROR_401
    ORG_MW -.-> ERROR_403
    VALIDATE_MW -.-> ERROR_404
    VALIDATE_MW -.-> ERROR_500

    style AUTH_MW fill:#f3e5f5
    style AUDIT_MW fill:#e1f5fe
    style SUCCESS fill:#e8f5e9

Technology Stack Details

Frontend Stack

Framework: Next.js 15 with App Router and Turbopack
Language: TypeScript (strict mode)
Styling: Tailwind CSS 4
UI Components: shadcn/ui (Radix UI primitives)
State Management: Zustand + React Query
Forms: React Hook Form + Zod validation
Charts: Recharts
Rich Text: TipTap editor

Backend Stack

Runtime: Node.js 20 LTS
API: Next.js API Routes (92 endpoints)
ORM: Prisma (28 models)
Database: PostgreSQL 16
Cache: Redis 7
Auth: Clerk (organization multi-tenancy)
Email: Resend (POPIA-compliant)

Infrastructure

CDN: Cloudflare
Frontend Hosting: Vercel
Backend Hosting: Railway
Monitoring: Sentry
CI/CD: GitHub Actions
Container: Docker

DevOps

Version Control: Git + GitHub
Package Manager: pnpm
Testing: Jest (233 tests) + Playwright (28 tests)
Linting: ESLint + TypeScript
Code Quality: 96% test coverage

Performance Characteristics

Response Times (Average)

API Endpoints: <150ms
Page Load: <1.5s
Database Queries: <100ms
Dashboard Load: <0.8s

Scalability

Concurrent Users: 10,000+
Database: Horizontal scaling with read replicas
Application: Vertical & horizontal scaling
Cache: Redis cluster for high availability

Availability

Uptime Target: 99.9%
Backup Frequency: Every 6 hours
Recovery Time: <1 hour
Data Retention: 5+ years (POPIA)

Last Updated: October 15, 2025 Verified: Production v0.1.4

System Design - ThriveSend B2B2G

System Design - ThriveSend B2B2G

System Architecture Overview

Multi-Tenant B2B2G Architecture

Component Architecture

Request Flow Architecture

Deployment Architecture

Security Architecture

API Architecture

Technology Stack Details

Frontend Stack

Backend Stack

Infrastructure

DevOps

Performance Characteristics

Response Times (Average)

Scalability

Availability

Related Documentation