🎯 Projects Module

The Projects Module is the operational backbone of DashClicks' digital marketing service delivery platform. It orchestrates the complete lifecycle of managed services—from initial order placement through onboarding, setup, active management, and ongoing optimization—ensuring seamless coordination between agencies, their clients, and service delivery teams.

🎯 Overview

Purpose

The Projects module solves the complex challenge of managing multi-tiered digital marketing service delivery at scale. It handles:

Service Lifecycle Management: Orchestrating the full journey from order → onboarding → setup → active delivery → reporting
Multi-Party Coordination: Managing interactions between platform admins, agency partners, end clients, and delivery teams
Onboarding Workflows: Streamlining client data collection through form management and approval processes
Task & Communication: Enabling real-time collaboration with status tracking and notification systems
Documentation & Reporting: Maintaining comprehensive records of service delivery, files, and performance metrics
Client Portal Integration: Providing white-labeled client dashboards with SSO and scoped access controls

Supported Service Types

The module manages delivery for these managed subscription services:

Advertising Services:

Meta (Facebook) Ads - Campaign setup, optimization, and reporting
Google Ads - Search, Display, Shopping campaigns
TikTok Ads - Creative-first advertising campaigns

SEO & Local Services:

SEO Management - Technical optimization and content strategy
Backlink Building - Link acquisition campaigns
GBP (Google Business Profile) - Local ranking optimization

Content Services:

Content Creation - Blog posts, articles, website content
Social Media Posts - Multi-platform content creation

Web & Listings:

Website Development - Custom site builds
Business Listings Management - Multi-directory presence

Service Tiers

Most services are offered in performance-based tiers:

Pro - Entry-level service with essential features
Plus - Enhanced service with expanded deliverables
Platinum - Premium tier with maximum deliverables and priority support

📁 Directory Structure

internal/api/v1/projects/
├── 📄 index.js                        # Express router setup
├── 📄 README.md                       # Module documentation
│
├── 📂 controllers/                    # Request handlers (13 controllers)
│   ├── accounts.controller.js         # Sub-account listing for projects
│   ├── activity.controller.js         # Activity history tracking
│   ├── analytics.controller.js        # Revenue and performance metrics
│   ├── dashboard.controller.js        # Dashboard data aggregation
│   ├── files.controller.js            # File storage management
│   ├── notebooks.controller.js        # Project documentation
│   ├── onboardings.controller.js      # Onboarding workflow management
│   ├── pulses.controller.js           # Real-time project updates
│   ├── reports.controller.js          # Service delivery reports
│   ├── subscriptions.controller.js    # Subscription lifecycle
│   ├── task.controller.js             # Task and communication management
│   └── work-summary.controller.js     # Weekly work summaries
│
├── 📂 routes/                         # API route definitions with validation
│   ├── index.js                       # Route aggregation
│   └── ...                            # (mirrors controllers)
│
├── 📂 services/                       # Business logic layer (13 services)
│   ├── accounts.service.js            # Account retrieval and filtering
│   ├── task.service.js                # Task orchestration (2066 lines)
│   ├── onboardings.service.js         # Onboarding state machine (780 lines)
│   ├── analytics.service.js           # Performance calculations
│   ├── files.service.js               # File CRUD operations
│   └── ...                            # (other services)
│
├── 📂 validations/                    # Joi validation schemas
│   └── ...                            # (validation for each feature)
│
├── 📂 utils/                          # Utility functions
│   └── analytics.js                   # Time/cost calculations
│
└── 📂 tests/                          # Test suites (7 test files)

🗄️ MongoDB Collections

📚 Detailed Schema: See Database Collections Documentation

Core Projects Collections

`projects.tasks`

Purpose: Task management and communication between parties
Model: shared/models/projects-tasks.js
Primary Use: Task creation, status tracking, communication threads, pending actions

`projects.pulse`

Purpose: Real-time project status updates and milestones
Model: shared/models/projects-pulse.js
Primary Use: Status broadcasts, timeline events, stakeholder notifications

`projects-files`

Purpose: Document storage with metadata
Model: shared/models/projects-file.js
Primary Use: File uploads, client-specific document management, access control

`projects-notebooks`

Purpose: Structured project documentation
Model: shared/models/projects-notebook.js
Primary Use: Service documentation, internal notes, client-visible docs

`projects-dashboard-preferences`

Purpose: Client portal SSO and scope configuration
Model: shared/models/projects-dashboard-preferences.js
Primary Use: White-label dashboard setup, permission scoping, sub-account filtering

Store Collections (Read-Heavy)

`_store.orders`

Purpose: Order records linking subscriptions to services
Operations: Read (primary), Status updates
Usage: Order lookups, timeline tracking, onboarding status

`_store.subscriptions`

Purpose: Active subscription data from Stripe
Operations: Read (primary), Metadata updates
Usage: Service status, billing info, cancellation tracking

Onboarding Collections

`onboarding.typeform.requests`

Purpose: Onboarding form requests sent to clients
Operations: Create, Read, Update status
Usage: Form generation, tracking sent forms, resend logic

`onboarding.typeform.response`

Purpose: Client-submitted onboarding form data
Operations: Create, Read, Update (approval workflow)
Usage: Response validation, approval/issue tracking, data extraction

🏗️ Architecture Overview

Design Pattern: Service-Oriented Architecture

The Projects module follows a layered architecture:

Request → Route (Validation) → Controller (HTTP) → Service (Business Logic) → Models (Data)

Key Responsibilities:

Coordination Layer (Controllers) - HTTP handling, auth checks, response formatting
Business Logic Layer (Services) - Complex aggregations, multi-collection orchestration, state machines
Data Access Layer (Models) - MongoDB operations, schema validation

Critical Design Decisions

Dashboard Preferences Pattern:

The module implements sophisticated access control for white-labeled client portals:

// SSO and Client Dashboard access controlled via preferences
if (dashboardPreferences?.allow_client_dashboard || dashboardPreferences?.sso) {
  // Apply scoped filtering
  options.parent_account = dashboardPreferences.parent_account;
  options._id = { $in: dashboardPreferences.sub_account_ids };

  // Apply scope restrictions
  if (!dashboardPreferences.scopes.includes('activity.onboarding_dates')) {
    delete response.createdAt; // Hide sensitive timestamps
  }
}

This enables:

White-labeled client portals with custom branding
Granular permission control at feature level
Multi-sub-account access for agency clients
Selective data exposure based on scopes

Why Aggregation-Heavy?

Multi-tenant data requires complex filtering across 5-10 collections
Performance: Single aggregation pipeline vs multiple queries
Client portal access requires sophisticated permission checks at query time
Rich data presentation needs (tasks with order + subscription + account + user data)

🔗 Feature Modules

Core Service Management

📘 Accounts - Sub-account listing and filtering for project views
� Activity - Event logging, status change history, audit trails
📙 Analytics - Revenue metrics, profit calculations, retention tracking
📕 Dashboard - Dashboard data aggregation and client portal views

Task & Communication

�📘 Task Management - Task lifecycle, communication threads, pending actions, multi-party coordination
📗 Onboardings - Form workflows, approval processes, client data collection
📙 Pulses - Real-time project status updates and milestones

Data & Documentation

📕 Files - Document storage, client-specific file organization, secure access control
📔 Notebooks - Project documentation, structured notes, collaborative editing
📓 Reports - Service delivery reports, performance tracking, client reporting
� Work Summaries - Weekly work summary generation

Subscription Management

� Subscriptions - Service status tracking, order timelines, subscription lifecycle

🔄 Core Data Flows

Order to Active Service Flow

flowchart TD
    A[🛒 Order Placed in Store] --> B[📦 Order Created]
    B --> C{Service Type?}
    C -->|Managed Service| D[📋 Generate Onboarding Request]
    C -->|Self-Service| E[✅ Auto-Approve]

    D --> F[📤 Send Onboarding Form]
    F --> G{Form Submitted?}
    G -->|⏳ Waiting| H[Status: sent]
    G -->|✅ Submitted| I[Status: received]

    I --> J[👀 Review Submission]
    J --> K{Issues Found?}
    K -->|❌ Issues| L[Status: issues]
    K -->|✅ Approved| M[Status: approved]

    L --> N[📝 Request Revision]
    N --> G

    M --> O[🚀 Queue Setup Tasks]
    E --> O
    O --> P[📊 Active Service Delivery]

    style A fill:#e1f5ff
    style P fill:#e1ffe1
    style L fill:#ffe1e1

Task Communication Flow

sequenceDiagram
    participant Agency
    participant Platform
    participant Client
    participant System

    Platform->>System: Create Task (type: onboarding_issues)
    System->>System: Store in projects.tasks
    System->>Agency: Notify via Socket + Email

    Agency->>System: Reply to Task
    System->>Platform: Notify Response

    Platform->>System: Update Status (completed)
    System->>System: Log Activity
    System->>Agency: Notify Completion
    System->>Client: Update Dashboard (if applicable)

🔐 Authentication & Authorization

Authentication Layers

JWT Token Validation - All routes require valid JWT
Account Association - User must belong to account
Dashboard Preferences - SSO/client dashboard users have restricted access
Role-Based Access - Some features require specific roles (e.g., PROJECT_ROLES)

Authorization Patterns

Agency Access (Full Access):

{
  account_id: agency_id,
  parent_account: agency_id,
  // Full access to all sub-accounts
}

Client Dashboard Access (Scoped):

{
  dashboardPreferences: {
    allow_client_dashboard: true,
    parent_account: agency_id,
    sub_account_ids: [allowed_sub_account_ids],
    scopes: ['tasks.view', 'files.download', ...]
  }
}

⚙️ Configuration

Key Constants

// Managed service types
const MANAGED_SUBSCRIPTIONS = [
  'facebook_ads',
  'google_ads',
  'tiktok_ads',
  'seo',
  'backlinks',
  'gbp_ranking',
  'content',
  'social_posts',
  'site',
  'listings',
];

// Task types
const TASK_TYPES = [
  'onboarding_issues',
  'onboarding_submission',
  'onboarding_qa',
  'onboarding_approved',
  'subscription_past_due',
  'request',
  'approval',
  'setup',
];

// Onboarding statuses
const ONBOARDING_STATUSES = ['pending', 'sent', 'received', 'issues', 'approved'];

Supported Scopes

const AVAILABLE_SCOPES = [
  'tasks.view',
  'tasks.create',
  'tasks.reply',
  'files.view',
  'files.download',
  'files.upload',
  'activity.view',
  'activity.onboarding_dates',
  'reports.view',
  'analytics.view',
  'onboardings.view',
];

⚠️ Important Notes

🚨 Data Isolation: Client dashboard queries MUST filter by dashboardPreferences.sub_account_ids to prevent data leakage
💡 Scope Enforcement: Always check dashboardPreferences.scopes before exposing sensitive data
🔒 Task Creator Field: The creator field distinguishes platform tasks ('dashclicks') from agency tasks
⚡ Aggregation Performance: Ensure proper indexes on parent_account, account_id, subscription, order_id
📊 Real-time Updates: Task status changes emit socket events for live dashboard updates
🔄 Onboarding State Machine: Status progression is mostly one-way (except issues→received via revision)

Store Module - Order and subscription management
Accounts Module - Account hierarchy and permissions
Database Collections - Detailed schema documentation

Last Updated: 2025-10-08
Module Version: v1
API Base Path: /v1/projects

🎯 Overview​

Purpose​

Supported Service Types​

Service Tiers​

📁 Directory Structure​

🗄️ MongoDB Collections​

Core Projects Collections​

projects.tasks​

projects.pulse​

projects-files​

projects-notebooks​

projects-dashboard-preferences​

Store Collections (Read-Heavy)​

_store.orders​

_store.subscriptions​

Onboarding Collections​

onboarding.typeform.requests​

onboarding.typeform.response​

🏗️ Architecture Overview​

Design Pattern: Service-Oriented Architecture​

Critical Design Decisions​

🔗 Feature Modules​

Core Service Management​

Task & Communication​

Data & Documentation​

Subscription Management​

🔄 Core Data Flows​

Order to Active Service Flow​

Task Communication Flow​

🔐 Authentication & Authorization​

Authentication Layers​

Authorization Patterns​

⚙️ Configuration​

Key Constants​

Supported Scopes​

⚠️ Important Notes​

🔗 Related Documentation​

Documentation Assistant