Configuration

Comprehensive guide to configuring the DashClicks Backend microservices for development, testing, and production environments.

Environment Variables

The DashClicks Backend uses environment variables for configuration. The main .env file is located in the root directory of the backend project.

Core System Configuration

General Settings:

Variable	Description	Example Value
API_VERSION	API version identifier	v1
API_BASE_URL	Base URL for API router	http://localhost:5001
NODE_ENV	Environment mode	development
DEBUG_MODE	Enable debug logging	true
INTERNAL_BASE_URL	Internal API service URL	http://localhost:5002
EXTERNAL_BASE_URL	External API service URL	http://localhost:5003
INTERNAL_V2_BASE_URL	Internal API v2 service URL (Hono)	http://localhost:5102
HONO_APP_PORT	Hono application port	5102
AI_SERVICE_BASE_URL	AI service URL (Deno)	http://localhost:5010

Database Configuration:

Variable	Description	Example Value
MONGO_DB_URL	MongoDB connection string	mongodb+srv://devs:pass@sandbox-free.tirqwqb.mongodb.net/dashclicks-sandbox
MONGO_TEST_DB_URL	Test database connection string	mongodb+srv://devs:pass@sandbox-free.tirqwqb.mongodb.net/dashclicks-sandbox

Redis Configuration (Required for socket services):

Variable	Description	Example Value
REDIS_HOST	Primary Redis server hostname	127.0.0.1
REDIS_PORT	Primary Redis server port	6379
REDIS_STORE_HOST	Store Redis server hostname	127.0.0.1
REDIS_STORE_PORT	Store Redis server port	6378

Authentication & Security

Variable	Description	Example Value
JWT_SECRET	JWT token signing secret	somesupersecret
APP_SECRET	Application secret key	somesupersecret
APP_MISC_SECRET	Miscellaneous app secret	somesupersecret
LEADS_SECRET	Leads processing secret	somesupersecret
CLIENT_ID	OAuth client identifier	602f112cba0f0f08b442291e
CLIENT_SECRET	OAuth client secret	2f727e8848729fda7f19d27ae2ab73e9896f2b4b...
CLIENT_REDIRECT_URI	OAuth redirect URI	https://api.dashclicks.com/auth/oauth/callback
TOKEN_EXPIRY	JWT token expiry time	60m
TOKEN_EXPIRY_SECONDS	JWT token expiry in seconds	3600

Service Configuration

Service URLs & Communication:

Variable	Description	Example Value
SOCKET_API	General Socket service URL	http://localhost:4000
GENERAL_SOCKET	General Socket service URL (alias)	http://localhost:4000
CONVERSATION_SOCKET	Conversation Socket service URL	http://localhost:6001
CONVERSATION_EMIT_URL	Socket emission endpoint	http://localhost:4000
NOTIFICATION_SERVICE_URL	Notification service URL	http://localhost:5008
QM_WEBHOOK_URL	Queue Manager webhook URL	http://localhost:6002

Business & Utility Services:

Variable	Description	Example Value
SHORT_URL_SERVICE	URL shortening service	http://localhost:5002/v1/url
SHORT_DOMAIN	Short URL domain	https://urlme.app
SEND_EMAIL_URL	Email sending service endpoint	http://localhost:5001/v1/e/sendgrid/mail
SEND_SMS_URL	SMS sending service endpoint	http://localhost:5001/v1/e/twilio/send
CRM_PEOPLE_URL	CRM contacts endpoint	http://localhost:5001/v1/crm/contacts/people
DEALS_PIPELINES_URL	CRM pipelines endpoint	http://localhost:5001/v1/crm/pipelines

File Storage & CDN:

Variable	Description	Example Value
WASABI_IMAGE_DOWNLOAD	Wasabi image download endpoint	http://localhost:5001/v1/e/wasabi/download_by_key
WASABI_PUBLIC_IMAGE_DOWNLOAD	Public Wasabi image endpoint	http://localhost:5001/v1/e/wasabi/public/download_by_key
WASABI_PUBLIC_URL	Wasabi public CDN URL	https://open.s3.wasabisys.com
WASABI_ENDPOINT	Wasabi S3 endpoint	s3.wasabisys.com
WASABI_REGION	Wasabi storage region	us-east-1

Third-Party Integration Configuration

Stripe Payment Processing:

Variable	Description	Example Value
STRIPE_SECRET_KEY	Stripe secret API key	sk_test_YOUR_KEY
STRIPE_CLIENT_ID	Stripe Connect client ID	ca_YOUR_CLIENT_ID
STRIPE_REDIRECT_URL	OAuth redirect URL	https://ngrok-url.app/v1/e/stripe/auth/callback
SETUP_PRODUCT	Setup product ID	prod_M8h5Gq7SL2QkQ9

Twilio SMS/Voice:

Variable	Description	Example Value
TWILIO_ACCOUNT_SID	Twilio account identifier	ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
TWILIO_AUTH_TOKEN	Twilio authentication token	YOUR_TWILIO_AUTH_TOKEN
TWILIO_MESSAGING_GROUP_SID	Messaging service group SID	MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
TWILIO_API_KEY	Twilio API key	SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
TWILIO_API_SECRET	Twilio API secret	YOUR_TWILIO_API_SECRET
TWIML_APP_SID	TwiML application SID	APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
TWILIO_WEBHOOK_URL	Twilio webhook endpoint	https://ngrok-url.app/v1/e/twilio/webhook
TWILIO_SMS_URL	SMS webhook endpoint	https://ngrok-url.app/v1/e/twilio/webhook/inbound

Google Services:

Variable	Description	Example Value
GOOGLE_CLIENT_ID	Google OAuth client ID	your_google_client_id
GOOGLE_CLIENT_SECRET	Google OAuth client secret	your_google_client_secret
GOOGLE_ADS_DEV_TOKEN	Google Ads developer token	your_google_ads_dev_token
GOOGLE_ADS_API_VERSION	Google Ads API version	v13
GOOGLE_ANALYTICS_CLIENT_ID	Analytics OAuth client ID	your_google_analytics_client_id
GOOGLE_ANALYTICS_CLIENT_SECRET	Analytics OAuth client secret	your_google_analytics_client_secret
GOOGLE_CLOUD_PROJECT_ID	Google Cloud project ID	your_google_cloud_project_id
GOOGLE_PAGE_SPEED_API_KEY	PageSpeed Insights API key	your_google_page_speed_api_key

SendGrid Email Service:

Variable	Description	Example Value
SENDGRID_API_KEY	SendGrid API key	SG.xxxxxx
SENDGRID_EVENT_WEBHOOK_URL	SendGrid event webhook	http://localhost:5001/v1/e/sendgrid/webhook
SENDGRID_INBOUND_WEBHOOK_URL	SendGrid inbound webhook	http://localhost:5001/v1/e/sendgrid/webhook/inbound
SENDGRID_TEMPLATE_VIOLATION_SUSPENSION	Violation suspension template ID	d-30a82cd8576143cca3782165691339fe
SENDGRID_TEMPLATE_VIOLATION_WARNING	Violation warning template ID	d-2eb1a53a371e40008fd58614737a41df
SENDGRID_TEMPLATE_DOMAIN_FAILED	Domain failed template ID	d-a7c4a7d28e384d03bd894181134fd353
SENDGRID_GROUP_GENERAL	General email group ID	22798
SENDGRID_GROUP_SYSTEM	System email group ID	22799
SENDGRID_DEFAULT_DOMAIN_ID	Default domain ID	11945395
SENDGRID_SUBUSER_IP	Subuser IP address	159.183.200.57

Facebook/Meta Integration:

Variable	Description	Example Value
FACEBOOK_CLIENT_ID	Facebook app client ID	3246944435541246
FACEBOOK_CLIENT_SECRET	Facebook app client secret	YOUR_FACEBOOK_CLIENT_SECRET
FACEBOOK_API_VERSION	Facebook API version	v20.0
FACEBOOK_VERIFY_TOKEN	Webhook verification token	tokendata
FACEBOOK_INBOUND_REDIRECT	OAuth redirect URL	http://localhost:5001/v1/inbound/facebook/auth/callback
FACEBOOK_INBOUND_WEBHOOK	Inbound webhook URL	http://localhost:5001/v1/inbound/webhookfb
FACEBOOK_ADS_REDIRECT_URL	Ads OAuth redirect URL	https://ngrok-url.app/v1/e/facebook/auth/callback
FACEBOOK_ADS_WEBHOOK_URL	Ads webhook URL	https://playground-api.dashclicks.com/v1/inbound/facebook/webhook

CRM Integration Configuration

HubSpot CRM:

Variable	Description	Example Value
HUBSPOT_AUTHORIZE_URL	OAuth authorization URL	https://app.hubspot.com/oauth/authorize
HUBSPOT_REDIRECT_URL	OAuth redirect URL	http://localhost:5001/v1/e/hubspot/auth/callback
HUBSPOT_TOKEN_URL	Token exchange URL	https://api.hubapi.com/oauth/v1/token
HUBSPOT_SCOPES	Required OAuth scopes	contacts
HUBSPOT_GRANT_TYPE	OAuth grant type	authorization_code

Salesforce CRM:

Variable	Description	Example Value
SALESFORCE_AUTH_URL	OAuth authorization URL	https://login.salesforce.com/services/oauth2/authorize
SALESFORCE_TOKEN_URL	Token exchange URL	https://login.salesforce.com/services/oauth2/token
SALESFORCE_REDIRECT_URL	OAuth redirect URL	http://localhost:5001/v1/e/salesforce/auth/callback
SALESFORCE_AUTH_SCOPES	Required OAuth scopes	full
SALESFORCE_GRANT_TYPE	OAuth grant type	authorization_code

Zoho CRM:

Variable	Description	Example Value
ZOHO_AUTHORIZE_URL	OAuth authorization URL	https://accounts.zoho.com/oauth/v2/auth
ZOHO_ACCESS_TOKEN_URL	Token exchange URL	https://accounts.zoho.com/oauth/v2/token
ZOHO_REDIRECT_URL	OAuth redirect URL	http://localhost:5001/v1/e/zoho/auth/callback
ZOHO_SCOPE_PERMISSIONS	Required API permissions	ZohoCRM.modules.ALL
ZOHO_JWT_SECRET	JWT signing secret	zoho

Pipedrive CRM:

Variable	Description	Example Value
PIPE_DRIVE_REDIRECT_URL	OAuth redirect URL	http://localhost:5001/v1/e/pipedrive/auth/callback

Keap (Infusionsoft) CRM:

Variable	Description	Example Value
KEAP_BASE_URL	Keap API base URL	https://api.infusionsoft.com/crm/rest/v1
KEAP_REDIRECT_URL	OAuth redirect URL	http://localhost:5001/v1/e/keap/auth/callback
KEAP_JWT_SECRET	JWT signing secret	keap

Email Marketing Integration Configuration

MailChimp:

Variable	Description	Example Value
MAILCHIMP_AUTHORIZATION_URL	OAuth authorization URL	https://login.mailchimp.com/oauth2/authorize
MAILCHIMP_TOKEN_URL	Token exchange URL	https://login.mailchimp.com/oauth2/token
MAILCHIMP_REDIRECT_URI	OAuth redirect URL	http://localhost:5001/v1/e/mailchimp/auth/callback
MAILCHIMP_DATACENTER_URL	Datacenter metadata URL	https://login.mailchimp.com/oauth2/metadata
MAILCHIMP_JWT_SECRET	JWT signing secret	mailchimp

Constant Contact:

Variable	Description	Example Value
CONSTANTCONTACT_AUTH_ENDPOINT	OAuth authorization URL	https://api.cc.email/v3/idfed
CONSTANTCONTACT_ACCESS_TOKEN_ENDPOINT	Token exchange URL	https://idfed.constantcontact.com/as/token.oauth2
CONSTANTCONTACT_REDIRECT_URL	OAuth redirect URL	http://localhost:5001/v1/e/constantcontact/auth/callback
CONSTANTCONTACT_AUTH_SCOPE	Required OAuth scope	contact_data

ActiveCampaign:

Variable	Description	Example Value
ACTIVECAMPAIGN_API_VERSION	API version path	/api/3

Queue Manager Configuration

Business Process Queues (Actual settings from .env):

Variable	Description	Current Value
QM_SUBSCRIPTION_CANCEL	Enable subscription cancellation queue	true
QM_SUBSCRIPTION_ACTIVATE	Enable subscription activation queue	true
QM_CONTACTS	Enable contacts processing queue	true
QM_DEALS	Enable deals processing queue	true
QM_DEALS_AUTOMATIONS	Enable deals automation queue	true
QM_REPUTATION	Enable reputation management queue	true
QM_INSTASITES_BUILD	Enable InstaSites build queue	true
QM_INSTASITES_PURGE	Enable InstaSites purge queue	true
QM_INSTAREPORT_BUILD	Enable InstaReport build queue	true
QM_HOOKS	Enable webhooks processing queue	true

Support & Communication Queues:

Variable	Description	Current Value
QM_SUPPORT_SNOOZE	Enable support ticket snooze queue	true
QM_SUPPORT_MESSAGE_STATUS	Enable support message status queue	true
QM_SUPPORT_NOTIFICATION	Enable support notification queue	true
QM_SUPPORT_COMMUNICATION_CHECK	Enable communication check queue	true

Billing & Account Management:

Variable	Description	Current Value
QM_BILLING_NEW_AUTH	Enable billing authentication queue	true
QM_BILLING_CONTACTS	Enable billing contacts queue	true

Queue Configuration Settings:

Variable	Description	Current Value
SUBSCRIPTION_CANCEL_QUEUES_ATTEMPTS	Max attempts for subscription cancel	10
DAYS_UNTIL_INSTASITE_PURGE	Days before InstaSite purge	90

Business Configuration

Currency & Pricing:

Variable	Description	Current Value
BASE_CURRENCY	Default currency	USD
ADDITIONAL_APP_FEE_CENTS	Additional app fee in cents	5
ADDITIONAL_APP_FEE_PERCENTAGE	Additional app fee percentage	0.0045
ADDITIONAL_APP_FEE_SUBSCRIPTION_PERCENTAGE	Subscription fee percentage	0.005

Site Management:

Variable	Description	Current Value
DUDA_INTERNAL_ENDPOINT	Duda API internal endpoint	http://localhost:5001/v1/e/duda
DUDA_SITES_DOMAIN	Duda sites API domain	https://api.duda.co/api/sites/multiscreen
DUDA_USER	Duda API username	23d70bc914
DUDA_PASSWORD	Duda API password	Hh8iL7Zz9sQ7
DUDA_TOKEN	Duda API token	61198bd65332564be0eac436

Reviews & Templates:

Variable	Description	Current Value
REQUEST_REVIEW_TEMPLATE_ID	SendGrid review request template ID	d-ff9f9394c39e41b8b8440b340220731f

External Service APIs

SEMrush SEO Analytics:

Variable	Description	Example Value
SEMRUSH_API_URL	SEMrush API base URL	https://api.semrush.com/
SEMRUSH_DATABASE	Default database region	US

Yext Local Listings:

Variable	Description	Example Value
YEXT_API_KEYS	Yext API key	15bd68d8636553d827ce4b66db6063d1
YEXT_API_KEY_SCAN	Yext scan API key	8368b6559b71e36953e0ce03f82d1f34
YEXT_API_VPARAM	Yext API version parameter	20200525
YEXT_SCAN_EXPIRY_DAYS	Scan result expiry days	2

Firebase Cloud Messaging:

Variable	Description	Example Value
FCM_SERVER_KEY	FCM server key	AAAAUztqSMs:APA91bGdgHGt_PUFG...

System Configuration

Debug & Monitoring:

Variable	Description	Example Value
LEGACY_DEFAULTS_DEBUG	Enable legacy debug mode	1
PROXY_URL	Proxy server URL	https://proxy.mydashmetrics.com
WHITE_LABEL_DOMAIN	White label domain	https://whitelabeldomain.com
UPSTREAM_SERVER	Upstream proxy server	10.0.3.185:80

Conversation System:

Variable	Description	Example Value
CONVERSATION_REPLY_TO_EMAIL	Default reply-to email	inbox@conversations-dev.dashboardnotifications.com

pnpm Monorepo Configuration

The DashClicks Backend uses pnpm for package management with workspace configuration defined in pnpm-workspace.yaml:

Development Scripts

Initial Setup (Required first run):

# Install all dependencies and copy shared files
pnpm run build

Shared Files Management:

# Copy shared files after editing /shared folder
pnpm run copySharedFiles

# Update shared models and utilities across all services
pnpm run copySharedFiles

Testing:

# Run all tests across services
pnpm test

# Generate coverage reports
pnpm run coverage

Documentation:

# Build and serve documentation
pnpm run docs

# Start documentation frontend
pnpm run docs-frontend

AI Service Configuration (Deno)

The AI service runs on Deno (not Node.js) and uses ai-service/.env:

ai-service/.env

# Service Configuration
PORT=5010
NODE_ENV=development

# AI Configuration (keys not set in provided .env)
OPENAI_API_KEY=
OPENAI_DEFAULT_MODEL=gpt-4o-mini

Shared Files Configuration

Critical: Understanding Git Ignore Patterns

The monorepo uses specific .gitignore patterns that prevent committing changes to service-level shared folders:

.gitignore

# Shared files are Git-ignored in ALL services
*/models/
*/utilities/

# This means these folders won't be committed:
internal/api/v1/models/
internal/api/v1/utilities/
external/Integrations/models/
external/Integrations/utilities/
conversation-socket/models/
conversation-socket/utilities/
dashboard-gateway/models/
dashboard-gateway/utilities/
general-socket/models/
general-socket/utilities/
queue-manager/models/
queue-manager/utilities/

Shared Models Configuration

The shared/models/_globalSchemaOptions.js file configures all Mongoose schemas:

shared/models/_globalSchemaOptions.js

module.exports = {
  // Global schema options applied to all models
  timestamps: true,
  versionKey: false,

  // Transform JSON output
  toJSON: {
    transform: function (doc, ret) {
      ret.id = ret._id;
      delete ret._id;
      delete ret.__v;
      return ret;
    },
  },

  // Transform Object output
  toObject: {
    transform: function (doc, ret) {
      ret.id = ret._id;
      delete ret._id;
      delete ret.__v;
      return ret;
    },
  },
};

Development Scripts Configuration

Add these scripts to your workflow:

# Initial setup - installs dependencies and copies shared files
pnpm install

# Copy shared files after editing
pnpm run copySharedFiles

# Run tests across all services
pnpm test

# Generate coverage reports
pnpm run coverage

# Build documentation
pnpm run docs

Integration API Keys Setup

Stripe Payment Processing

1. Create Stripe Account: Visit stripe.com and create an account
2. Get API Keys: Dashboard → Developers → API keys (Vinod Nimbalkar's test account is being used for Stripe local development)
3. Test vs Live Keys: Use sk_test_ for development, sk_live_ for production
4. Webhook Setup (Production + Local Testing):

Production (Dashboard)

• Create webhook endpoint: https://yourdomain.com/v1/store/webhook
• Select minimal events first:
  • payment_intent.succeeded
  • payment_intent.payment_failed
  • invoice.paid
  • invoice.payment_failed
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
• Copy the signing secret (e.g. whsec_...) → set as STRIPE_WEBHOOK_SECRET in .env

Local Development

1. Install Stripe CLI: https://stripe.com/docs/stripe-cli

2. Authenticate:

   stripe login

3. Start a listener forwarding to your local service (adjust port/path if routed through API Router):

   # If the webhook is handled by the API Router
   stripe listen --forward-to localhost:5000/v1/store/webhook

   Or, if handled directly by Internal API on 5002:

   stripe listen --forward-to localhost:5002/store/webhook

4. Copy the printed signing secret (looks like whsec_...) → set in .env.local:

   STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxx

5. (Optional) Expose publicly via ngrok (if Stripe Dashboard needs to hit your machine directly):

   ngrok http 5000
   # Then add https://your-ngrok-id.ngrok.io/v1/store/webhook in Stripe dashboard

6. Trigger test events:

   # Core payment intents
   stripe trigger payment_intent.succeeded
   stripe trigger payment_intent.payment_failed

Twilio SMS/Voice

1. Create Twilio Account: Visit twilio.com
2. Get Credentials: Console Dashboard → Account SID and Auth Token
3. Buy Phone Number: Phone Numbers → Manage → Buy a number
4. Configure Webhooks:
   • SMS: https://yourdomain.com/v1/e/twilio/webhook/inbound
   • Voice: https://yourdomain.com/v1/e/twilio/webhook

Google Ads & Analytics

1. Create Google Cloud Project: console.cloud.google.com
2. Enable APIs: Google Ads API, Analytics Reporting API
3. Create OAuth 2.0 Credentials: APIs & Services → Credentials
4. Get Developer Token: Google Ads → Tools & Settings → API Center

OpenAI for AI Service

1. Create OpenAI Account: platform.openai.com
2. Generate API Key: API Keys → Create new secret key
3. Set Usage Limits: Billing → Usage limits (prevent overcharges)
4. Monitor Usage: Usage → Dashboard

VS Code Debug Configuration

The monorepo includes comprehensive VS Code launch configurations in .vscode/launch.json:

Individual Service Debugging

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Internal API (5002)",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/internal/app.js",
      "env": {
        "NODE_ENV": "development",
        "PORT": "5002"
      },
      "console": "integratedTerminal",
      "restart": true,
      "runtimeArgs": ["--inspect"]
    },
    {
      "name": "External API (5003)",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/external/index.js",
      "env": {
        "NODE_ENV": "development",
        "PORT": "5003"
      },
      "console": "integratedTerminal",
      "restart": true
    }
  ]
}

Service Health Check

Each service provides a simple /status endpoint for health monitoring:

# Check service status
curl http://localhost:5002/status     # Internal API
curl http://localhost:5003/status     # External API

# Expected response format
{
  "status": "ok"
}

Running Services for Development

🚨 CRITICAL: Always use VSCode debugger configurations to start services. Never run services directly with node commands.

1. Open VS Code in the backend workspace
2. Go to Run and Debug panel (Ctrl+Shift+D)
3. Use "Start All Services" compound configuration to launch all 7 services
4. Individual services can be debugged separately using their named configurations

This ensures proper environment loading, debugging capabilities, and service interdependency management.

Development Best Practices

Environment Management

• Keep .env file in root directory only
• Use different .env files for different environments if needed
• Never commit .env files to version control
• Use .env.sample as a template for other developers

Service Dependencies

• MongoDB: Required for all services (data storage)
• Redis: Required for socket services (real-time features)
• External APIs: Optional for basic functionality, required for integrations

Queue Manager Best Practices

• Set queue flags to false in development to prevent background processing
• Enable only necessary queues for your development work
• Use QM_SCHEDULE_UTILIZATION_MONITORING=true for monitoring in development

---

This configuration documentation reflects the actual DashClicks Backend implementation. For additional setup guidance, see the Quick Start Guide or Architecture Overview.