Skip to main content

Service Documentation

Detailed documentation for all microservices in the DashClicks Backend ecosystem. Each service has its own purpose, API endpoints, and configuration requirements.

Service Categories​

🏗️ Gateway & Routing Services​

Dashboard Gateway (Port 5000)​

Frontend proxy service for the React dashboard application.

Key Features:

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

Documentation:

API Router (Port 5001)​

Main API gateway that routes requests and handles authentication conversion.

Key Features:

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

Documentation:

🔧 Core Business Services​

Internal API (Port 5002)​

Handles proprietary DashClicks features with /v1/* routes.

Service Modules:

External API (Port 5003)​

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

Integration Categories:

Marketing & Advertising:

Analytics & Tracking:

CRM & Sales:

  • HubSpot - CRM and marketing automation
  • Keap - CRM and marketing automation
  • Pipedrive - Sales CRM and pipeline management
  • Salesforce - Enterprise CRM platform
  • Zoho - Business suite and CRM integration

Communication:

  • FCM - Firebase Cloud Messaging
  • Twilio - SMS, voice, and communication APIs

Payment Processing:

  • SquareUp - Payment processing and POS
  • Stripe - Payment processing and billing
  • Tipalti - Payment automation and compliance

Infrastructure & Utilities:

Business Services:

🔄 Real-time & Communication Services​

Conversation Socket (Port 6001)​

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

Key Features:

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

Documentation:

General Socket (Port 4000)​

General-purpose real-time events and notifications.

Key Features:

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

Documentation:

⚡ Background Processing Services​

Queue Manager (Port 6002)​

Background job processing and task scheduling service.

Key Features:

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

Documentation:

Notification Service (Port 5008)​

Handles email and SMS notifications.

Key Features:

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

Documentation:

🤖 AI & Advanced Services​

AI Service (Port 5010)​

Advanced AI/ML capabilities using Deno runtime with OpenAI integration.

Key Features:

  • OpenAI GPT integration
  • Content generation
  • Chat completions
  • Text analysis

Technology Stack:

  • Runtime: Deno 2.0+
  • Framework: Hono
  • Language: TypeScript
  • AI Provider: OpenAI

Documentation:

🛠️ Utility Services​

Currency Service (Port 5005)​

Multi-currency conversion and localization support.

Documentation:

CallRail Service (Port 5004)​

CallRail recording proxy and analytics integration.

Documentation:

Yext Publishers Service (Port 5006-5007)​

Yext publisher data and image management.

Documentation:

Proxy Server (Port 6003)​

General proxy functionality for internal routing.

Documentation:

Google Maps Service (Port 5009)​

Google Maps and location services integration.

Documentation:

Shared Architecture​

Shared Models​

150+ Mongoose schemas shared across all services.

Model Categories:

Shared Utilities​

Common business logic and helper functions.

Utility Categories:

Common Services​

Conversation-specific services shared between Internal API and Conversation Socket.

Common Modules:

Development Patterns​

Service Communication​

  • All services communicate through the API Router (5001)
  • Services use JWT tokens for authentication
  • Inter-service calls go through Router, not direct connections

Shared Code Management​

  • NEVER edit files in service-level models/ or utilities/ folders
  • Always edit source files in /shared/ and /common/ folders
  • Run pnpm run copySharedFiles after making changes
  • Service-level folders are Git-ignored and get overwritten

Environment Configuration​

  • Each service has its own environment variables
  • Shared configuration in root .env file
  • Service-specific configs in individual service folders

Testing Strategy​

  • Unit tests for individual service components
  • Integration tests for API endpoints
  • End-to-end tests for complete user flows
  • Coverage requirements: 40% branches, 50% functions

Deployment Architecture​

Development Environment​

  • All services run through VS Code debugger configurations
  • Individual service debugging for focused development
  • "Start All" compound configuration for full stack testing

Production Environment​

  • Container-based deployment with Docker
  • Kubernetes orchestration for scaling
  • Load balancing through Traefik
  • Service discovery and health monitoring

Monitoring & Observability​

Health Monitoring​

  • /status endpoint on all services
  • Database connectivity checks
  • External service dependency monitoring
  • Performance metrics collection

Logging Strategy​

  • Structured logging with consistent formats
  • Request tracing and correlation IDs
  • Error aggregation and alerting
  • Service-specific log levels

Performance Monitoring​

  • Request/response timing
  • Database query performance
  • Memory and CPU usage tracking
  • Rate limiting and throttling metrics

Getting Started​

  1. Quick Start Guide - Get all services running locally
  2. Configuration Guide - Environment setup and variables
  3. Architecture Overview - System design and patterns
  4. API Reference - Common API patterns and authentication
  5. Troubleshooting - Common issues and solutions

Contributing​

When working with DashClicks Backend services:

  1. Use VS Code debugger - Never run services directly in terminal
  2. Edit shared files correctly - Use /shared/ and /common/ folders only
  3. Test thoroughly - Run tests for affected services
  4. Follow patterns - Maintain consistency across services
  5. Document changes - Update relevant service documentation

For detailed contribution guidelines, see each service's individual documentation.

💬

Documentation Assistant

Ask me anything about the docs

Hi! I'm your documentation assistant. Ask me anything about the docs!

I can help you with:
- Code examples
- Configuration details
- Troubleshooting
- Best practices

Try asking: How do I configure the API?
09:30 AM