DashClicks Back-End

Welcome to the DashClicks Back-End - a comprehensive microservices architecture powering the DashClicks platform for digital marketing agencies worldwide.

What is DashClicks?

DashClicks is a complete white-label digital marketing platform that provides agencies with tools for CRM, analytics, billing, project management, and client communications. The back-end is a sophisticated monorepo containing 15+ microservices that work together to deliver a seamless experience.

Architecture Overview

🏗️ Microservices Architecture

Independent Services: Each service handles specific business domains
Service Communication: HTTP proxying through centralized API Router (Using Traefik on production)
Scalable Design: Each service can be deployed and scaled independently
Shared Components: Common models and utilities across all services

🚀 Modern Tech Stack

Node.js + Express (JS): Fast, scalable server-side JavaScript
Deno + Hono (TS): Lightweight runtime for AI services, TypeScript support
MongoDB + Mongoose: Flexible document database with ODM
Socket.IO: Real-time communication for chat and live updates
Redis: Caching and session management for socket services
pnpm: Fast, disk space efficient package manager for monorepos
Jest: Comprehensive testing framework with coverage requirements

Core Services & Ports

The DashClicks back-end consists of multiple specialized microservices as defined in .vscode/launch.json:

🔌 Primary Services

Dashboard Gateway (5000) - Frontend proxy for React dashboard
API Router (5001) - Main API gateway, routes to internal/external services/AI service (Local Development Only)
Internal API (5002) - Proprietary DashClicks features (/v1/* routes)
External API (5003) - 3rd party integrations (/v1/e/* routes)

🔄 Real-time & Communication Services

Conversation Socket (6001) - Real-time messaging with Socket.IO
General Socket (4000) - General real-time events and notifications
Notification Service (5008) - Email/SMS notifications and alerts
Queue Manager (6002) - Background job processing and task scheduling

🛠️ Utility & Integration Services

AI Service (5010) - Advanced AI/ML capabilities using Deno runtime with OpenAI integration
Callrail Recordings (5004) - Call recording proxy service
Currency Service (5005) - Multi-currency support
Yext Publishers (5006) - Publisher data management
Yext Publishers Logo (5007) - Publisher image management
Proxy Server (6003) - Internal proxy routing
Google Maps Integration (5009) - Maps and location services

Prerequisites

Before you begin, ensure you have the following installed:

📋 Required Software

Node.js v18+ (Download)
Deno v2.0+ (Download) - Required for AI Service
pnpm v10+ (npm install -g pnpm)
MongoDB running locally or MongoDB Atlas access
Redis for socket services and caching
VS Code with debugger extensions
Git for version control

🔧 Optional but Recommended

Docker for containerized services
Postman for API testing
MongoDB Compass for database visualization
Redis Insight for Redis monitoring

Getting Started - Production Setup

⚡ Step 1: Environment Setup

Clone the repository and install dependencies using pnpm:

# 1. Clone the repository
git clone https://github.com/DashClicks-LLC/Back-End.git
cd Back-End

# 2. Install pnpm globally if not already installed
npm install -g pnpm

# 3. Install all dependencies across the monorepo
pnpm install

🔐 Step 2: Environment Configuration

Set up your environment files for all services:

# 1. Copy the main environment template
cp .env.sample .env

# 2. Edit the main .env file with your credentials
nano .env

Required Environment Variables

Add these essential variables to your .env file from the sample .env.sample

🔄 Step 3: Shared Files Management

CRITICAL: Always run this after environment setup:

# Copy shared models and utilities to all services
pnpm run copySharedFiles

Understanding Shared Architecture

/shared/models/ - 150+ Mongoose schemas used across all services
/shared/utilities/ - Common business logic and helper functions
Service-level models/ and utilities/ folders are Git-ignored
Never edit files in service-level folders - they get overwritten!

🚀 Step 4: Redis Setup

IN local DEVELOPMENT, Redis is optional (Required for Queue Manager, Sockets, Notification Service) but recommended for full functionality using Docker

Running Services with VS Code Debugger

🚨 IMPORTANT: We ONLY run services through VS Code debugger configurations - never directly in terminal!

🐛 Launch Configurations

Our .vscode/launch.json contains 20+ pre-configured debug setups:

Core API Services

Open VS Code → Debug Panel (Ctrl+Shift+D) → Select any service:

Dashboard Gateway (5000) - Frontend proxy service (Always Run)
API Router (5001) - Main routing service (Always Run)
API Internal (5002) - Internal business logic and proprietary features
API External (5003) - Third-party integrations

Real-time & Communication Services

SOCKET Conversation (6001) - Real-time messaging with Socket.IO
General Socket (4000) - General real-time events and notifications
Notification Service (5008) - Email/SMS notifications and alerts
Notification queue (5008) - Queue-enabled notification processing

Background Processing Services

Queue Manager (6002) - Background job processing and task scheduling

Utility & Integration Services

MISC - Callrail Recordings (5004) - Call recording proxy service
MISC - Currency (5005) - Multi-currency conversion utilities
MISC - Yext Publishers (5006) - Publisher data management
MISC - Yext Publishers Logo (5007) - Publisher image management
MISC - Proxy (5007) - Internal proxy routing
Proxy server (6003) - General proxy functionality

Specialized Services

AI Service (5010) - Advanced AI/ML capabilities using Deno runtime
External - Google maps (5009) - Maps and location services integration

Testing & Development Services

Test forms notifications - Forms notification testing utility
Test forms contact notifications - Contact reminder testing utility
Function - Deals automation - Deals automation testing

🚀 Starting Development Environment

Method 1: Start All Services (Recommended)

# In VS Code:
# 1. Go to Debug Panel (Ctrl+Shift+D)
# 2. Select "Start All" compound configuration
# 3. Press F5 or click green play button

Method 2: Individual Service Development

For focused development on specific services:

# In VS Code Debug Panel:
# 1. Select the specific service (e.g., "API Internal")
# 2. Press F5 to start with debugger attached
# 3. Set breakpoints in your code
# 4. Debugger will pause at breakpoints for inspection

🔍 Debugger Features

Automatic Restart: Services restart on file changes
Environment Variables: Loaded from .env files
Breakpoint Support: Full debugging capabilities
Console Output: All service logs in Debug Console
Variable Inspection: Real-time variable values
Call Stack: Complete execution trace

Essential Development Workflow

🚨 CRITICAL: Shared Folder Rules

⚠️ NEVER edit files in service-level models/ or utilities/ folders

The shared code system has Git ignore patterns that developers must understand:

# These folders are Git-ignored in ALL services:
internal/api/v1/models/          # ❌ DON'T EDIT
internal/api/v1/utilities/       # ❌ DON'T EDIT
external/Integrations/models/    # ❌ DON'T EDIT
external/Integrations/utilities/ # ❌ DON'T EDIT
conversation-socket/models/      # ❌ DON'T EDIT
# ... and so on for all services

✅ Correct Development Workflow

# 1. Edit shared files only
nano shared/models/user.js
nano shared/utilities/auth.js

# 2. Copy changes to all services
pnpm run copySharedFiles

# 3. Restart affected services in VS Code debugger
# (Services DO NOT auto-restart on file changes)

# 4. Test your changes with debugger breakpoints

🔄 Development Commands

# Install dependencies (use pnpm, not npm!)
pnpm install

# Copy shared files after editing them
pnpm run copySharedFiles

# Run tests across all services
pnpm test

# Generate coverage reports (40% branch, 50% function minimum)
pnpm run coverage

# Build documentation
pnpm run docs

Monorepo Structure

Understanding the DashClicks back-end organization:

📁 Core Directories

Back-End/
├── .vscode/
│   └── launch.json              # 20+ VS Code debug configurations
├── shared/                      # Shared code for all services
│   ├── models/                  # 150+ Mongoose schemas
│   └── utilities/               # Common business logic
├── internal/                    # Internal API service (5002)
│   └── api/v1/                  # Internal business endpoints
├── external/                    # External API service (5003)
│   └── Integrations/            # 25+ third-party integrations
├── dashboard-gateway/           # Frontend proxy (5000)
├── router/                      # API routing service (5001)
├── conversation-socket/         # Real-time messaging (6001)
├── general-socket/              # General events (4000)
├── queue-manager/               # Background jobs (6002)
├── notifications/               # Email/SMS service (5008)
├── ai-service/                  # AI features using Deno (5010)
├── misc/                        # Utility services (5004-5007)
│   ├── callrail-recordings/     # Call recording proxy
│   ├── currency/                # Currency conversion
│   ├── proxy-server/            # Internal proxy (6003)
│   ├── yext-publishers/         # Publisher data
│   └── yext-publishers-logo/    # Publisher images
├── functions/                   # Serverless functions
├── tests/                       # Centralized testing suite
└── docs/                        # Documentation system

🌐 Service URLs (Development)

When all services are running via VS Code debugger:

Core API Services

Dashboard Gateway: http://localhost:5000 (Frontend Proxy)
API Router: http://localhost:5001 (Main Gateway)
Internal API: http://localhost:5002 (Proprietary Features)
External API: http://localhost:5003 (Third-party Integrations)

Real-time & Communication Services

General Socket: http://localhost:4000 (Real-time Events)
Conversation Socket: http://localhost:6001 (Messaging)
Notification Service: http://localhost:5008 (Email/SMS)

Background Processing Services

Queue Manager: http://localhost:6002 (Background Jobs)

Utility & Integration Services

Callrail Recordings: http://localhost:5004 (Call Recording Proxy)
Currency Service: http://localhost:5005 (Currency Conversion)
Yext Publishers: http://localhost:5006 (Publisher Data)
Yext Publishers Logo: http://localhost:5007 (Publisher Images)
Google Maps Integration: http://localhost:5009 (Maps & Location)
Proxy Server: http://localhost:6003 (Internal Proxy)

Specialized Services

AI Service: http://localhost:5010 (AI/ML Features - Deno Runtime)

Key Features & Integrations

🔌 Third-Party Integrations

DashClicks connects with 30+ external services located in external/Integrations/:

Marketing & Advertising

Google Ads - PPC campaign management and optimization
Facebook - Social media advertising and analytics
BingAds - Microsoft advertising platform integration
TikTok - Social media advertising for TikTok platform
Google Analytics - Web analytics and reporting
SEMrush - SEO and competitive analysis tools

CRM & Sales Management

Salesforce - Enterprise CRM integration
Pipedrive - Sales pipeline management
HubSpot - Inbound marketing and sales platform
Keap - Small business CRM and automation
Zoho - Business suite integration
ActiveCampaign - Email marketing and automation

Communication & Messaging

Twilio - SMS/Voice communication services
SendGrid - Email delivery and marketing
Mailchimp - Email marketing campaigns
ConstantContact - Email marketing platform
FCM - Firebase Cloud Messaging for push notifications
Beamer - Product update notifications

Call Tracking & Analytics

Callrail - Call tracking and analytics
CallTrackingMetrics - Advanced call tracking solutions

Payments & Financial Services

Stripe - Payment processing and subscriptions
Squareup - Point of sale and payment solutions
Tipalti - Automated payables and payments

Website & Development Tools

Duda - Website builder integration
Cloudflare - CDN and security services
GoogleBusiness - Google My Business integration
GoogleMap - Maps and location services
Yext - Digital knowledge management
Wasabi - Cloud storage solutions

Data & APIs

RapidAPI - API marketplace and integration platform

📊 Core Platform Features

Based on internal/api/v1/ modules, DashClicks provides:

Account & User Management

Accounts - Multi-tenant account management and domain configuration
Users - User authentication, roles, permissions, and profile management
Auth - JWT-based authentication, session management, and OAuth integrations

Customer Relationship Management

CRM - Complete contact management, deal tracking, and pipeline automation
Activities - User activity tracking and audit logs
Forms - Lead capture forms and form submission handling

Sales & Marketing Tools

Funnels - Sales funnel creation and conversion tracking
Templates - Marketing template management and customization
URL Shortener - Branded link shortening and click tracking
Reviews - Online reputation management and review monitoring

Website & Content Management

InstaSites - Automated website generation and management
Sites - Agency website builder and hosting platform
InstaReports - Automated reporting and analytics generation
Public - Public-facing content and landing pages

Communication & Collaboration

Conversations - Client messaging and internal team communication
Conversation-v2 - Enhanced real-time messaging system
Notifications Center - Centralized notification management

Business Operations

Store - White-label marketplace for digital marketing products
Billing - Subscription management, invoicing, and payment processing
Projects - Task management and project collaboration tools
OneBalance - Unified billing and credit management system

System & Administration

Admin - System administration and configuration management (DashClicks internal use only)
Webhooks - External service webhook handling and processing
Filters - Data filtering and search functionality
Inbound - Lead capture and inbound marketing automation

Analytics & Reporting

Shared - Shared analytics and reporting components
Mobile App - Mobile application API endpoints

Advanced Features

Affiliates - Partner and affiliate program management
OAuth - Third-party application authentication
CORS Proxy - Cross-origin request handling

Database Architecture

🗄️ MongoDB Collections

The system uses 150+ Mongoose models organized by domain in /shared/models/:

Core Business Models

Account Management: account.js, account-user.js, account-credit.js, account-signup-code.js, account-public-request.js, account-import-results.js
User Management: user.js, workspace-*.js, user-*.js
CRM & Sales: contact.js, deal.js, pipeline.js, automation.js, automation-log.js, crm-log.js, crm-note.js, crm-tag.js
Billing & Commerce: billing-*.js (charges, customers, disputes, products, subscriptions), store-*.js, consumer-*.js
Analytics & Reporting: analytics-*.js (callrail, facebook-ads, google-analytics, seo, tiktok), semrush.js, campaign-data.js

Communication & Messaging Models

Conversations: conversation.js, conversation-*.js (channel, group, message, prospect, room), communication.js
Notifications: notification-*.js, fcm-notification.js, fcm-token.js, expo-push-tokens.js
Forms & Lead Capture: forms-*.js, lead-*.js, prospect-*.js

Content & Website Management

Sites & Templates: site.js, sites-*.js, template.js, templates-*.js, agency-website.js, agency-website-template.js
InstaSites: instasites-*.js, instasite-*.js
InstaReports: instareports-*.js, report-*.js
Projects: project.js, project-*.js, task-*.js

Third-Party Integration Models

API Authentication: *-key.js, *-token.js patterns for service credentials
- Google: google-*.js (ads, analytics, business, map tokens)
- Social Media: facebook-*.js, tiktok-*.js, bing-ads-token.js
- Email Marketing: mailchimp-*.js, constant-contact-key.js, active-campaign-key.js
- CRM Integrations: salesforce-*.js, hubspot-*.js, pipedrive-*.js
- Call Tracking: callrail-key.js, calltrackingmetrics-key.js
- Payment Processing: stripe-*.js, tipalti-*.js
- Website Tools: duda-*.js, yext-*.js

System & Administrative Models

API Management: api-*.js (apps, grants, refresh-tokens, scopes, sessions)
OAuth & Authentication: oauth-*.js, session-*.js
Queue Management: queue-*.js, csv-queue.js, contact-queue.js, edocs-queue.js
Webhooks & Events: webhook-*.js, event-*.js
Admin & Teams: admin-team.js, team-*.js

Specialized Feature Models

Affiliates: affiliate-*.js, affiliates-leaderboard.js
Reviews & Reputation: review-*.js, reputation-*.js
Scheduling: availability-scheduler.js, event-type*.js, scheduler-*.js
E-Documents: edocs-*.js (categories, contacts, documents, files, templates)
Filters & Search: filter.js, fields-filter.js
Currency & Localization: currency.js, timezone.js

🔧 Database Connection & Initialization

The system uses a centralized database connection utility in shared/utilities/db.js:

Connection Management

const { connect, isConnected, disconnect } = require('./service-name/utilities/db');

// Initialize MongoDB connection with event logging
await connect({
  uri: process.env.MONGO_DB_URL,
  initiator: 'service-name',
  options: { maxPoolSize: 10 },
  overrideEvents: [], // or ['connecting'] to skip default events
});

Key Features

Automatic Event Logging: Registers MongoDB lifecycle events (connecting, connected, open, reconnected, disconnected, close, error)
Connection Pooling: Default maxPoolSize of 10 connections
Error Handling: Comprehensive error logging with service context
Graceful Shutdown: Clean disconnection with proper logging
Connection State Monitoring: isConnected() helper for health checks
Event Customization: Configurable event logging per service

Connection States

readyState 0: Disconnected
readyState 1: Connected (target state)
readyState 2: Connecting
readyState 3: Disconnecting

Best Practices

// Service initialization pattern
const db = require('./shared/utilities/db');

async function startService() {
  try {
    // Connect with service-specific logging
    await db.connect({
      initiator: 'internal-api',
      overrideEvents: ['connecting'], // Skip default connecting event
    });

    // Check connection health
    if (db.isConnected()) {
      console.log('Service ready with database connection');
    }
  } catch (error) {
    console.error('Failed to initialize database:', error.message);
    process.exit(1);
  }
}

// Graceful shutdown
process.on('SIGTERM', async () => {
  await db.disconnect('internal-api');
  process.exit(0);
});

Schema Patterns

Global Configuration: shared/models/_globalSchemaOptions.js defines consistent schema defaults
Validation Patterns: Standardized validation rules across all models
Mongoose Middleware: Pre/post hooks for automation and data integrity
Index Optimization: Strategic indexing for query performance
Timestamp Management: Automatic createdAt/updatedAt with immutable createdAt option

Testing & Quality Assurance

🧪 Testing Architecture

# Run all tests across services
pnpm test

# Run tests with coverage
pnpm run coverage

# Run specific service tests
pnpm test -- --testPathPattern=internal

# Run integration tests
pnpm test -- tests/integration

📊 Coverage Requirements

40% minimum branch coverage
50% minimum function coverage
50% minimum line coverage
MongoDB Memory Server for isolated testing
Supertest for API endpoint testing

🔧 Jest Configuration

Multi-project setup with service-specific configs
Shared test utilities in /tests/
Mock data in /tests/fixtures/
Integration tests in /tests/integration/

Advanced Development Topics

🚀 Background Job Processing

The Queue Manager service (port 6002) is a comprehensive background processing system with multiple specialized queues and cron jobs:

Queue Categories & Environment Controls

# Core Business Process Queues
QM_SUBSCRIPTION_CANCEL=false           # Subscription cancellation processing
QM_SUBSCRIPTION_ACTIVATE=false         # Subscription activation workflows
QM_SUBSCRIPTION_PENDING_SUBACCOUNT_CHARGE=false  # Pending subaccount billing
QM_SUBSCRIPTION_CHARGE_MAINACCOUNT=false         # Main account billing

# Contact & CRM Management
QM_CONTACTS=false                       # Contact processing and automation
QM_CONTACTS_EXPORT=false               # Contact data export jobs
QM_CONTACTS_EXPORT_CLEANUP=false       # Export cleanup tasks
QM_DEALS=false                         # Deal processing workflows
QM_DEALS_AUTOMATIONS=false             # Deal automation triggers

# Website & Content Generation
QM_INSTASITES_BUILD=false              # InstaSites website building
QM_INSTASITES_PURGE=false              # InstaSites cleanup (90 days)
QM_INSTAREPORT_BUILD=false             # InstaReports generation
QM_SITES_BUILD_THUMBNAILS=false        # Site thumbnail generation
QM_FUNNELS_BUILD_THUMBNAILS=false      # Funnel thumbnail generation
QM_FUNNELS_CLONING=false               # Funnel duplication processes

# Financial & Billing Operations
QM_ONEBALANCE_BALANCE_RELOAD=false          # OneBalance credit reloading
QM_ONEBALANCE_BALANCE_RELOAD_STREAM=false   # Real-time balance updates
QM_ONEBALANCE_BALANCE_CHARGE=false          # OneBalance charging
QM_ONEBALANCE_BALANCE_CHARGE_STREAM=false   # Real-time charge processing
QM_BILLING_NEW_AUTH=false                   # New billing authorization
QM_BILLING_CONTACTS=false                   # Billing contact management

# Communication & Support
QM_SUPPORT_SNOOZE=false                # Support ticket snoozing
QM_SUPPORT_MESSAGE_STATUS=false        # Support message status updates
QM_SUPPORT_NOTIFICATION=false          # Support notifications
QM_SUPPORT_COMMUNICATION_CHECK=false   # Communication health checks

# System & Infrastructure
QM_HOOKS=false                         # Webhook processing and retries
QM_WEBHOOK=false                       # General webhook handling
QM_TRIGGERS=false                      # System trigger processing
QM_PROJECTS=false                      # Project management automation
QM_AFFILIATES=false                    # Affiliate program processing
QM_REPUTATION=false                    # Online reputation monitoring

# Domain & Infrastructure Management
QM_LIGHTNING_DOMAIN_VALIDATION=false   # Lightning domain validation
QM_LIGHTNING_DOMAIN_RENEWAL=false      # Domain renewal automation
QM_VERIFY_STRIPE_DOMAINS=false         # Stripe domain verification
QM_SITE_UPDATE_BUSINESS=false          # Business information updates
QM_CHECK_ACCOUNT_ACTIVE=false          # Account status validation

# Monitoring & Analytics
QM_SCHEDULE_UTILIZATION_MONITORING=true  # Resource utilization tracking (ENABLED)

Queue Manager Architecture

Based on the queue-manager/ folder structure:

Core Components:

Queues/ - Individual queue processors for each business domain
Crons/ - Scheduled task management organized by feature area
Streams/ - Real-time data processing streams
Triggers/ - Event-driven automation handlers
Services/ - Business logic services for queue operations

Specialized Queue Areas:

Accounts - Account lifecycle and management
Affiliates - Partner program automation
Billing - Financial transaction processing
Communication - Email/SMS notification delivery
Contacts - CRM contact synchronization
Conversations - Message processing and routing
Deals - Sales automation workflows
Domains - DNS and domain management
Funnels - Marketing funnel operations
InstaSites - Website building and deployment
InstaReports - Report generation and delivery
OneBalance - Credit system management
Reviews - Reputation monitoring
Sites - Website management and optimization
Store - E-commerce transaction processing
Webhooks - External service integration

Key Integrations & Services

# External Service Endpoints
DUDA_INTERNAL_ENDPOINT=http://localhost:5001/v1/e/duda
TWILIO_WEBHOOK_URL=https://...ngrok-free.app/v1/e/twilio/webhook
WASABI_PUBLIC_IMAGE_DOWNLOAD=http://localhost:5001/v1/e/wasabi/public/download_by_key
SHORT_URL_SERVICE=http://localhost:5002/v1/url

# Service Communication
API_BASE_URL=http://localhost:5001
SOCKET_API=http://localhost:4000
CONVERSATION_SOCKET=http://localhost:6001

Processing Capabilities

Subscription Management - Automated billing cycles, cancellations, and activations
Content Generation - Website building, report creation, and thumbnail generation
CRM Automation - Contact processing, deal workflows, and lead nurturing
Financial Operations - Payment processing, credit management, and billing
Communication Delivery - Email/SMS notifications and messaging
System Monitoring - Resource utilization and health checks
Domain Management - DNS validation, renewals, and verification
Webhook Processing - External service integration and retry logic
Data Synchronization - Real-time streams and batch processing
Reputation Monitoring - Review tracking and online presence management

🔌 Real-time Features

DashClicks uses dual Socket.IO services for comprehensive real-time communication:

Conversation Socket Service (Port 6001)

Dedicated messaging and communication hub:

Real-time Messaging - Client-to-client and internal team communication
Chat Rooms - Multi-participant conversation management
Message Delivery - Instant message routing and delivery confirmation
Conversation Management - Channel creation, group messaging, and prospect communication
Authentication Middleware - Secure socket connections with user verification
Message Persistence - Integration with conversation models for message history

Key Features:

Client messaging systems
Team collaboration tools
Prospect communication channels
Message threading and history
File sharing and media support
Typing indicators and read receipts

General Socket Service (Port 4000)

System-wide real-time event distribution:

Integration Modules (based on general-socket/Integrations/):

Conversation - Cross-service conversation events
LeadFinder - Real-time lead discovery notifications
LiveChat - Live chat widget functionality
Prospect - Prospect activity and status updates
RestAPI - API event broadcasting
Shared - Common real-time utilities
Utils - Socket utility functions

Authentication & Security:

is-auth.js - Standard user authentication middleware
is-auth-visitor.js - Visitor/guest authentication for public features
scope.js - Permission-based access control for socket events

Real-time Event Categories:

System Notifications - Platform-wide alerts and updates
Live Updates - Real-time data synchronization across services
Lead Tracking - Prospect activity and engagement monitoring
Widget Communication - Live chat and form submission events
Cross-service Events - Inter-service communication and state synchronization
Dashboard Updates - Real-time analytics and metrics updates

Architecture & Scaling

Service Communication:

# Inter-service socket communication
SOCKET_API=http://localhost:4000           # General Socket endpoint
CONVERSATION_SOCKET=http://localhost:6001  # Conversation Socket endpoint

Key Implementation Features:

Dual-Service Architecture - Specialized services for different real-time needs
Authentication Layers - Multiple auth middleware for different user types
Event Namespacing - Organized event routing by feature domain
Cross-Service Integration - Seamless communication between socket services
Modular Design - Plugin-based integration system for extensibility
Middleware Stack - Comprehensive authentication and authorization
Real-time Synchronization - Live data updates across all connected clients

Use Cases:

Client Communication - Agency-to-client messaging and support
Team Collaboration - Internal team chat and notifications
Live Chat Widgets - Website visitor engagement
System Alerts - Platform notifications and status updates
Lead Engagement - Real-time prospect interaction tracking
Dashboard Monitoring - Live analytics and performance metrics

🧠 AI Service Integration

The AI Service uses Deno (not Node.js):

# Configured in .vscode/launch.json as:
"runtimeExecutable": "deno"
"program": "${workspaceFolder}/ai-service/src/main.ts"

Hono framework for HTTP handling
TypeScript for type safety
OpenAI API integration
Separate containerization

Troubleshooting & Common Issues

🚨 Common Development Problems

Shared Files Not Updating

# Problem: Changes in shared/ not reflecting in services
# Solution: Always run after editing shared files
pnpm run copySharedFiles

Service Won't Start in Debugger

# Problem: Port already in use
# Solution: Check running processes
lsof -i :5001  # Replace with your port
kill -9 <PID>  # Kill the process

Environment Variables Not Loading

# Problem: .env not being read
# Solution: Check file locations
ls -la .env                    # Main environment
ls -la notifications/.env      # Notification service

🔍 Debugging Tips

Use VS Code Breakpoints: Set breakpoints in your code, debugger will pause
Console Logs: Use console.log() - output appears in Debug Console
Variable Inspection: Hover over variables during debug sessions
Call Stack: Use Debug Panel to trace execution flow
Environment Check: Verify .env variables in debug session

Next Steps for New Developers

🎯 Learning Path

Week 1: Environment & Structure

Complete environment setup using this guide
Start all services via VS Code debugger
Explore /shared/models/ to understand data structure
Review service-specific routes in each service directory

Week 2: Development Workflow

Make small changes in shared files
Practice pnpm run copySharedFiles workflow
Set breakpoints and debug API endpoints
Write basic tests following existing patterns

Week 3: Business Logic

Study controller → service → model patterns
Understand JWT authentication flow in shared/utilities/auth.js
Learn Socket.IO implementation for real-time features
Explore third-party integrations in external/Integrations/

Week 4: Advanced Features

Work with Queue Manager background jobs
Implement new API endpoints with proper validation
Add new integration following existing patterns
Contribute to test coverage improvements

🎉 Welcome to the Team!

You're now ready to contribute to the DashClicks Back-End! This monorepo powers a comprehensive platform serving thousands of digital marketing agencies worldwide.

Remember: Always use VS Code debugger, manage shared files properly, and leverage pnpm for package management. Happy coding! 🚀

Need help? Check the team documentation, ask in Teamwork chat, or set up a pair programming session with a senior developer.

What is DashClicks?​

Architecture Overview​

🏗️ Microservices Architecture​

🚀 Modern Tech Stack​

Core Services & Ports​

🔌 Primary Services​

🔄 Real-time & Communication Services​

🛠️ Utility & Integration Services​

Prerequisites​

📋 Required Software​

🔧 Optional but Recommended​

Getting Started - Production Setup​

⚡ Step 1: Environment Setup​

🔐 Step 2: Environment Configuration​

Required Environment Variables​

🔄 Step 3: Shared Files Management​

Understanding Shared Architecture​

🚀 Step 4: Redis Setup​

Running Services with VS Code Debugger​

🐛 Launch Configurations​

Core API Services​

Real-time & Communication Services​

Background Processing Services​

Utility & Integration Services​

Specialized Services​

Testing & Development Services​

🚀 Starting Development Environment​

Method 1: Start All Services (Recommended)​

Method 2: Individual Service Development​

🔍 Debugger Features​

Essential Development Workflow​

🚨 CRITICAL: Shared Folder Rules​

✅ Correct Development Workflow​

🔄 Development Commands​

Monorepo Structure​

📁 Core Directories​

🌐 Service URLs (Development)​

Core API Services​

Real-time & Communication Services​

Background Processing Services​

Utility & Integration Services​

Specialized Services​

Key Features & Integrations​

🔌 Third-Party Integrations​

Marketing & Advertising​

CRM & Sales Management​

Communication & Messaging​

Call Tracking & Analytics​

Payments & Financial Services​

Website & Development Tools​

Data & APIs​

📊 Core Platform Features​

Account & User Management​

Customer Relationship Management​

Sales & Marketing Tools​

Website & Content Management​

Communication & Collaboration​

Business Operations​

System & Administration​

Analytics & Reporting​

Advanced Features​

Database Architecture​

🗄️ MongoDB Collections​

Core Business Models​

Communication & Messaging Models​

Content & Website Management​

Third-Party Integration Models​

System & Administrative Models​

Specialized Feature Models​

🔧 Database Connection & Initialization​

Connection Management​

Key Features​

Connection States​

Best Practices​

Schema Patterns​

Testing & Quality Assurance​

🧪 Testing Architecture​

📊 Coverage Requirements​

🔧 Jest Configuration​

Advanced Development Topics​

What is DashClicks?

Architecture Overview

🏗️ Microservices Architecture

🚀 Modern Tech Stack

Core Services & Ports

🔌 Primary Services

🔄 Real-time & Communication Services

🛠️ Utility & Integration Services

Prerequisites

📋 Required Software

🔧 Optional but Recommended

Getting Started - Production Setup

⚡ Step 1: Environment Setup

🔐 Step 2: Environment Configuration

Required Environment Variables

🔄 Step 3: Shared Files Management

Understanding Shared Architecture

🚀 Step 4: Redis Setup

Running Services with VS Code Debugger

🐛 Launch Configurations

Core API Services

Real-time & Communication Services

Background Processing Services

Utility & Integration Services

Specialized Services

Testing & Development Services

🚀 Starting Development Environment

Method 1: Start All Services (Recommended)

Method 2: Individual Service Development

🔍 Debugger Features

Essential Development Workflow

🚨 CRITICAL: Shared Folder Rules

✅ Correct Development Workflow

🔄 Development Commands

Monorepo Structure

📁 Core Directories

🌐 Service URLs (Development)

Core API Services

Real-time & Communication Services

Background Processing Services

Utility & Integration Services

Specialized Services

Key Features & Integrations

🔌 Third-Party Integrations

Marketing & Advertising

CRM & Sales Management

Communication & Messaging

Call Tracking & Analytics

Payments & Financial Services

Website & Development Tools

Data & APIs

📊 Core Platform Features

Account & User Management

Customer Relationship Management

Sales & Marketing Tools

Website & Content Management

Communication & Collaboration

Business Operations

System & Administration

Analytics & Reporting

Advanced Features

Database Architecture

🗄️ MongoDB Collections

Core Business Models

Communication & Messaging Models

Content & Website Management

Third-Party Integration Models

System & Administrative Models

Specialized Feature Models

🔧 Database Connection & Initialization

Connection Management

Key Features

Connection States

Best Practices

Schema Patterns

Testing & Quality Assurance

🧪 Testing Architecture

📊 Coverage Requirements

🔧 Jest Configuration

Advanced Development Topics