Quick Start

Get the DashClicks Backend microservices up and running quickly with this step-by-step guide.

Prerequisites

Before you begin, ensure you have:

• Node.js 18+ (Download)
• Deno 2.0+ for AI Service (Download)
• pnpm 10+ package manager (npm install -g pnpm)
• MongoDB running locally or MongoDB Atlas access
• Redis for socket services (optional but recommended)
• VS Code with debugger extensions
• Git for version control
• Docker for containerized setup

Installation

1. Clone and Install Dependencies

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

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

# Install all dependencies across the monorepo
pnpm install

# Copy shared files (models, utilities, and conversation services)
pnpm copySharedFiles

2. Environment Configuration

Create a .env file in the root directory:

# Copy the sample environment file
cp .env.sample .env

3. Start DashClicks Services

The DashClicks Backend consists of multiple microservices. You can start them individually or use VS Code debugger configurations.

Option A: Using VS Code Debugger (Recommended)

1. Open the project in VS Code
2. Go to Run and Debug (Ctrl+Shift+D)
3. Select from available services:
   • Dashboard Gateway (Port 5000)
   • API Router (Port 5001)
   • API Internal (Port 5002)
   • API External (Port 5003)
   • General Socket (Port 4000)
   • SOCKET Conversation (Port 6001)
   • Queue Manager (Port 6002)
   • Notification Service (Port 5008)

Option B: Manual Service Startup (Not Recommended)

Start core services individually if needed:

# Start API Router (Main Gateway)
cd router && node app.js

# Start Internal API (in another terminal)
cd internal && node app.js

# Start External API (in another terminal)
cd external && node index.js

⚠️ Note: Manual startup bypasses environment configuration and debugging capabilities. Always prefer VS Code debugger method.

Verify Installation

1. Service Health Checks

Test that services are running:

# Check API Router (Main Gateway)
curl http://localhost:5001/status

# Check Internal API
curl http://localhost:5002/status

# Check External API
curl http://localhost:5003/status

Expected response from each service:

{
  "status": "ok"
}

2. Test Service Communication

Verify the API Router can proxy requests:

# Test Internal API through Router
curl http://localhost:5000/v1/

# Test External API through Router
curl http://localhost:5000/v1/e/

3. Check Service Logs

Monitor service startup in VS Code Debug Console or terminal output:

# Internal API should show:
{"method":null,"initiator":"internal","message":"MongoDB initiating connection","level":"log","callerPath":"..."}
{"method":null,"initiator":"internal","message":"MongoDB connected","level":"log","callerPath":"..."}
{"method":null,"initiator":"internal","message":"Express server running on port 5002","level":"log","callerPath":"..."}

# External API should show:
{"method":null,"initiator":"external","message":"MongoDB initiating connection","level":"log","callerPath":"..."}
{"method":null,"initiator":"external","message":"MongoDB connected","level":"log","callerPath":"..."}
{"method":null,"initiator":"external","message":"Express server running on port 5003","level":"log","callerPath":"..."}

# API Router should show:
Listening on 5001

What Happens Next?

When you start the DashClicks Backend services:

1. MongoDB Connection: Each service connects to the configured MongoDB database
2. Shared Files Loading: Models and utilities from /shared/ and conversation services from /common/ are loaded
3. Service Registration: Services register their endpoints and middleware
4. API Router Setup: The router configures proxy rules to internal/external APIs
5. Socket Services: Real-time services establish Redis connections (if configured)
6. Services Ready: All services become available for requests

Service Architecture

The DashClicks Backend follows a microservices pattern:

• ✅ API Router (5001): Main gateway that proxies requests to appropriate services
• ✅ Internal API (5002): Handles proprietary DashClicks features (/v1/* routes)
• ✅ External API (5003): Manages third-party integrations (/v1/e/* routes)
• ✅ Socket Services: Handle real-time communications and notifications
• ✅ Queue Manager: Processes background jobs and scheduled tasks
• ✅ Shared Components: Mongoose schemas from /shared/ and conversation services from /common/

Next Steps

Now that your DashClicks Backend is running:

1. Explore the API Reference - Learn about all available endpoints
2. Configure Advanced Settings - Environment variables and service configuration
3. Understanding Architecture - Deep dive into the microservices architecture

Troubleshooting

Common Issues

MongoDB Connection Failed

Error: MongoDB connection error

✅ Solution: Ensure MongoDB is running locally or check your MONGO_DB_URL in the .env file.

Port Already in Use

Error: listen EADDRINUSE :::5001

✅ Solution: Another service is using the port. Check running processes with lsof -i :5001 and kill if needed.

Shared Files Missing

Cannot find module './models/account'
Cannot find module './services/conversation.service'

✅ Solution: Run pnpm run copySharedFiles to populate:

• Models and utilities from /shared/ folder
• Conversation services and constants from /common/ folder

Service Won't Start

Application error during startup

✅ Solution:

• Check .env file exists and has required variables
• Ensure MongoDB is accessible
• Review VS Code Debug Console for detailed error messages

Getting Help

• Check the Configuration Guide for environment variables
• Review Architecture Documentation for system understanding
• Use VS Code debugger for detailed error investigation

---

🎉 Congratulations! Your DashClicks Backend microservices are now ready to power your digital marketing platform.