Architecture

Understanding the DashClicks Backend's microservices architecture helps you navigate the system, build features effectively, and troubleshoot issues.

Authentication Flow

DashClicks uses a unique authentication pattern where requests flow through multiple layers with session-based authentication:

graph LR
    Client[React Dashboard] --> DG[Dashboard Gateway :5000]
    DG --> Router[API Router :5001]
    Router --> Internal[Internal API :5002]
    Router --> External[External API :5003]
    Router --> Sockets[Socket Services]
    Router --> Queue[Queue Manager :6002]
      Router --> Notification[Notification Service :5008]

      Internal --> MongoDB[(MongoDB)]
      External --> MongoDB
      Sockets --> Redis[(Redis)]
      Queue --> MongoDB
      Notification --> MongoDB

    subgraph "Authentication Flow"
        Session[x-session-id header] --> JWT[JWT Access Token]
        JWT --> Verify[Token Verification]
    end

Authentication Process:

1. Frontend sends x-session-id header with all requests
2. Dashboard Gateway (5000) receives the session ID
3. Router (5001) converts x-session-id to JWT access token
4. All Services verify the JWT token for authentication
5. Services respond with authenticated data back through the chain

Microservices Architecture Overview

graph TB
    subgraph "Client Layer"
        Frontend[React Dashboard]
        Mobile[Mobile Apps]
        API_Clients[Third-party Clients]
    end

    subgraph "Gateway Layer"
        DashGW[Dashboard Gateway :5000]
        Router[API Router :5001]
    end

    subgraph "Core Services"
        Internal[Internal API :5002]
        External[External API :5003]
        Queue[Queue Manager :6002]
        Notification[Notification Service :5008]
    end

    subgraph "Real-time Services"
        ConvSocket[Conversation Socket :6001]
        GenSocket[General Socket :4000]
    end

    subgraph "Utility Services"
        AI[AI Service :5010]
        Currency[Currency :5005]
        Callrail[Callrail :5004]
        Yext[Yext Publishers :5006-5007]
        Proxy[Proxy Server :6003]
        GoogleMaps[Google Maps :5009]
    end

    subgraph "Data Layer"
        MongoDB[(MongoDB)]
        Redis[(Redis)]
    end

    Frontend --> DashGW
    Mobile --> DashGW
    API_Clients --> Router

    DashGW --> Router
    Router --> Internal
    Router --> External
    Router --> AI

    Internal --> MongoDB
    External --> MongoDB
    Queue --> MongoDB
    Notification --> MongoDB

    ConvSocket --> Redis
    GenSocket --> Redis
    Queue --> Redis

Core Components

1. Gateway Layer

Dashboard Gateway (Port 5000)

Frontend proxy service for the React dashboard application.

Key Responsibilities:

• Serves React frontend application
• Handles client-side routing and assets
• Initial session management
• Proxies API requests to Router

API Router (Port 5001)

Main API gateway that routes requests to appropriate services and handles authentication conversion.

Key Responsibilities:

• Authentication conversion: x-session-id → JWT tokens
• Request routing and proxying to internal/external services
• Rate limiting and security middleware
• Service discovery and load balancing

2. Core API Services

Internal API (Port 5002)

Handles proprietary DashClicks features with /v1/* routes.

Service Structure:

internal/api/v1/
├── accounts/           # Account management and settings
├── activities/         # Activity tracking and logging
├── admin/              # DashClicks internal app (admin panel)
├── affiliates/         # Affiliate program management
├── auth/               # Authentication and authorization
├── billing/            # Subscription and payment processing
├── conversation-v2/    # Messaging and communication (v2)
├── conversations/      # Legacy messaging system (v1)
├── cors-proxy/         # CORS proxy utilities
├── crm/                # Customer relationship management
├── filters/            # Data filtering and search
├── forms/              # Lead capture forms
├── funnels/            # Marketing funnel management
├── inbound/            # Inbound marketing tools
├── instareports/       # Automated reporting system
├── instasites/         # Website generation and management
├── mobile-app/         # Mobile application APIs
├── notifications-center/ # Notification management center
├── oauth/              # OAuth integrations
├── onebalance/         # Financial balance management
├── projects/           # Task and project management
├── public/             # Public-facing APIs
├── reviews/            # Review and reputation management
├── shared/             # Shared internal utilities
├── sites/              # Website management
├── store/              # E-commerce and store functionality
├── templates/          # Template management system
├── url-shortener/      # URL shortening service
├── users/              # User authentication and profiles
└── webhooks/           # Webhook handling and management

External API (Port 5003)

Manages third-party integrations with /v1/e/* routes.

Integration Structure:

external/Integrations/
├── ActiveCampaign/     # Email marketing automation
├── Beamer/             # Product announcement and changelog
├── BingAds/            # Microsoft Advertising (Bing Ads)
├── Callrail/           # Call tracking and analytics
├── CallTrackingMetrics/ # Advanced call tracking
├── Cloudflare/         # CDN and security services
├── ConstantContact/    # Email marketing platform
├── Duda/               # Website builder platform
├── Facebook/           # Social media marketing and ads
├── FCM/                # Firebase Cloud Messaging
├── GoogleAds/          # Google Ads PPC advertising
├── GoogleAnalytics/    # Web analytics and reporting
├── GoogleBusiness/     # Google My Business listings
├── GoogleMap/          # Google Maps and location services
├── Hubspot/            # CRM and marketing automation
├── Keap/               # CRM and marketing automation (formerly Infusionsoft)
├── Mailchimp/          # Email marketing and automation
├── Pipedrive/          # Sales CRM and pipeline management
├── RapidAPI/           # API marketplace integrations
├── Salesforce/         # Enterprise CRM platform
├── Semrush/            # SEO and digital marketing analytics
├── Sendgrid/           # Email delivery and marketing
├── Squareup/           # Payment processing and POS
├── Stripe/             # Payment processing and billing
├── TikTok/             # TikTok advertising and analytics
├── Tipalti/            # Payment automation and compliance
├── Twilio/             # SMS, voice, and communication APIs
├── Wasabi/             # Cloud storage and CDN
├── Yext/               # Local listings and reputation management
└── Zoho/               # Business suite and CRM integration

3. Real-time Services

Conversation Socket (Port 6001)

Real-time messaging service using Socket.IO for chat functionality.

Features:

• Real-time message delivery
• Room-based conversations
• Support chat system
• Message history and persistence
• Redis-based scaling

General Socket (Port 4000)

General-purpose real-time events and notifications.

Features:

• Live notifications
• System events broadcasting
• User presence tracking
• General real-time updates

4. Background Processing

Queue Manager (Port 6002)

Background job processing and task scheduling service.

Capabilities:

• Email queue processing
• Webhook delivery
• Scheduled task execution
• Report generation
• Data import/export jobs

Notification Service (Port 5008)

Handles email and SMS notifications.

Features:

• Email template processing
• SMS delivery via Twilio
• Notification preferences
• Delivery tracking and analytics

Shared Architecture

Shared Code Distribution

DashClicks uses a sophisticated shared code system to maintain consistency across services:

/shared/ Folder

Contains models and utilities copied to ALL services:

shared/
├── models/             # 150+ Mongoose schemas
│   ├── account.js      # Account management
│   ├── user.js         # User authentication
│   ├── contact.js      # CRM contacts
│   ├── deal.js         # Sales pipeline
│   └── ...             # All other models
└── utilities/          # Common business logic
    ├── auth.js         # Authentication helpers
    ├── db.js           # Database utilities
    ├── mail.js         # Email utilities
    └── ...             # All other utilities

/common/ Folder

Contains conversation-specific services shared between Internal API and Conversation Socket:

common/conversations/
├── constants/
│   └── bots.json       # Bot configuration
└── services/
    ├── conversation.service.js
    ├── message.service.js
    ├── room.service.js
    └── support.*.service.js

File Copy System

Critical Architecture Rule:

• Service-level models/ and utilities/ folders are Git-ignored
• Files are copied from /shared/ and /common/ during build process
• NEVER edit copied files - edit source files only

Copy Process:

pnpm run copySharedFiles

This command:

1. Copies /shared/models/ → service models/ folders
2. Copies /shared/utilities/ → service utilities/ folders
3. Copies /common/conversations/ → conversation services

---

This architecture provides a robust, scalable foundation for the DashClicks platform while maintaining clear separation of concerns and efficient development workflows.