Tags Controller

Path: internal/api/v1/funnels/controllers/tags.controller.js
Service: tagsService
Module: Funnels

---

Overview

The Tags controller manages funnel tags for organization and categorization. Tags enable users to group funnels by project, client, campaign, or any custom classification system.

Key Capabilities

• Tag Management: Create, read, update, delete tags
• Funnel Organization: Assign multiple tags to funnels
• Tag Filtering: Filter funnels by tags
• Search: Find tags by name
• Bulk Operations: Delete multiple tags at once

---

Methods

getTags()

Retrieves all tags for an account with optional search and pagination.

Route: GET /v1/funnels/tags
Auth: Required (account-scoped)

Request Query Parameters

{
  limit?: number;   // Results per page (default: 50)
  page?: number;    // Page number (0-indexed)
  skip?: number;    // Alternative to page (manual skip)
  search?: string;  // Search tag names
}

Response

{
  "success": true,
  "message": "SUCCESS",
  "data": [
    {
      "_id": "60d5ec49f1b2c72e8c8e4b60",
      "name": "E-commerce",
      "account_id": "60d5ec49f1b2c72e8c8e4b19",
      "funnel_count": 15,
      "color": "#FF6B6B",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    },
    {
      "_id": "60d5ec49f1b2c72e8c8e4b61",
      "name": "Lead Generation",
      "account_id": "60d5ec49f1b2c72e8c8e4b19",
      "funnel_count": 23,
      "color": "#4ECDC4",
      "created_at": "2024-01-10T14:30:00Z",
      "updated_at": "2024-01-10T14:30:00Z"
    },
    {
      "_id": "60d5ec49f1b2c72e8c8e4b62",
      "name": "Client: Acme Corp",
      "account_id": "60d5ec49f1b2c72e8c8e4b19",
      "funnel_count": 8,
      "color": "#95E1D3",
      "created_at": "2024-01-20T09:15:00Z",
      "updated_at": "2024-01-20T09:15:00Z"
    }
  ]
}

MongoDB Collections

Collection	Operation	Purpose
funnel_tags	find with pagination	Query tags by account
funnels	aggregate	Count funnels per tag

Search Functionality

• Case-insensitive search
• Partial match on tag name
• Example: search "lead" matches "Lead Generation", "Real Estate Leads"

---

createTag()

Creates a new tag for the account.

Route: POST /v1/funnels/tags
Auth: Required (account-scoped)

Request Body

{
  "name": "Spring Campaign 2024",
  "color": "#FF6B6B",
  "description": "All funnels for spring marketing campaign"
}

Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "60d5ec49f1b2c72e8c8e4b63",
    "name": "Spring Campaign 2024",
    "account_id": "60d5ec49f1b2c72e8c8e4b19",
    "color": "#FF6B6B",
    "description": "All funnels for spring marketing campaign",
    "funnel_count": 0,
    "created_at": "2024-01-22T20:00:00Z",
    "updated_at": "2024-01-22T20:00:00Z"
  }
}

MongoDB Collections

Collection	Operation	Purpose
funnel_tags	insertOne	Create new tag

Validation

• Name: Required, 1-50 characters
• Color: Optional, valid hex color code
• Duplicate check: Tag names must be unique per account

---

updateTag()

Updates an existing tag's properties.

Route: PUT /v1/funnels/tags/:tag_id
Auth: Required (account-scoped)

Request Parameters

{
  tag_id: string; // Tag ID (MongoDB ObjectId)
}

Request Body

{
  "name": "Spring Campaign 2024 (Updated)",
  "color": "#4ECDC4",
  "description": "Updated campaign description"
}

Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "60d5ec49f1b2c72e8c8e4b63",
    "name": "Spring Campaign 2024 (Updated)",
    "account_id": "60d5ec49f1b2c72e8c8e4b19",
    "color": "#4ECDC4",
    "description": "Updated campaign description",
    "funnel_count": 5,
    "created_at": "2024-01-22T20:00:00Z",
    "updated_at": "2024-01-22T20:30:00Z"
  }
}

MongoDB Collections

Collection	Operation	Purpose
funnel_tags	findOneAndUpdate	Update tag document

---

deleteTag()

Deletes one or multiple tags and removes them from all funnels.

Route: DELETE /v1/funnels/tags
Auth: Required (account-scoped)

Request Query Parameters

{
  tags: string; // Comma-separated tag IDs
}

Response

{
  "success": true,
  "message": "SUCCESS"
}

MongoDB Collections

Collection	Operation	Purpose
funnel_tags	deleteMany	Delete tag documents
funnels	updateMany	Remove tag references from funnels

Business Logic

• Deletes tag documents
• Removes tag IDs from all funnels using those tags
• Cascading delete ensures no orphaned references
• Supports bulk deletion via comma-separated IDs

---

Data Models

Tag Document

{
  _id: ObjectId;
  account_id: ObjectId;           // Owner account
  name: string;                   // Tag display name (unique per account)
  color?: string;                 // Hex color code (e.g., "#FF6B6B")
  description?: string;           // Optional description
  funnel_count?: number;          // Cached count of funnels using tag
  created_at: Date;
  updated_at: Date;
}

---

Business Logic & Workflows

Tag Assignment Flow

sequenceDiagram
    participant User
    participant Funnels
    participant Tags
    participant Database

    User->>Funnels: PUT /funnels/:id (update tags)
    Funnels->>Tags: Validate tag IDs
    Tags->>Database: Check tag existence
    Database-->>Tags: Tags exist
    Tags-->>Funnels: Validation passed
    Funnels->>Database: Update funnel.tags
    Funnels->>Tags: Update funnel_count for each tag
    Database-->>Funnels: Funnel updated
    Funnels-->>User: 200 OK

Tag Deletion Flow

sequenceDiagram
    participant User
    participant Tags
    participant Database

    User->>Tags: DELETE /tags?tags=id1,id2
    Tags->>Database: Find funnels using tags
    Database-->>Tags: Funnel list
    Tags->>Database: Remove tag IDs from funnels
    Tags->>Database: Delete tag documents
    Database-->>Tags: Deleted
    Tags-->>User: 200 OK

---

Tag Usage Patterns

Client Organization

{
  "tags": [
    { "name": "Client: Acme Corp", "color": "#FF6B6B" },
    { "name": "Client: Beta Inc", "color": "#4ECDC4" },
    { "name": "Client: Gamma LLC", "color": "#95E1D3" }
  ]
}

Campaign Organization

{
  "tags": [
    { "name": "Q1 2024", "color": "#FFD93D" },
    { "name": "Spring Campaign", "color": "#6BCF7F" },
    { "name": "Black Friday 2024", "color": "#000000" }
  ]
}

Funnel Type Organization

{
  "tags": [
    { "name": "Lead Generation", "color": "#4ECDC4" },
    { "name": "E-commerce", "color": "#FF6B6B" },
    { "name": "Webinar", "color": "#A8E6CF" },
    { "name": "Event", "color": "#FFD93D" }
  ]
}

Status Organization

{
  "tags": [
    { "name": "Active", "color": "#6BCF7F" },
    { "name": "Draft", "color": "#FFD93D" },
    { "name": "Archived", "color": "#CCCCCC" },
    { "name": "Testing", "color": "#FF6B6B" }
  ]
}

---

Integration Points

Funnel Filtering

• Purpose: Filter funnel lists by tags
• Integration: GET /funnels?tags=id1,id2 uses tag IDs
• Logic: Returns funnels with ANY of the specified tags (OR)

Reporting

• Purpose: Aggregate metrics by tag
• Metrics: Revenue per tag, conversions per tag
• Reports: Tag performance dashboard

---

Performance Considerations

Funnel Count Caching

• funnel_count cached in tag document
• Updated on funnel tag assignment/removal
• Recalculated daily via cron job for accuracy

Query Optimization

• Indexed fields: account_id, name
• Compound index: (account_id, name) for uniqueness
• Search uses text index on name field

Pagination

• Default limit: 50 tags (most accounts have < 50)
• Skip/limit for large tag collections
• No infinite scroll (full list typically small)

---

Security

Multi-Tenant Isolation

• All queries filtered by account_id
• Tags cannot be shared between accounts
• Delete operations verify tag ownership

Validation

• Tag names sanitized (no HTML/scripts)
• Color codes validated (hex format)
• Length limits enforced

---

Error Handling

Common Errors

// Tag not found
{
  "success": false,
  "message": "Tag not found",
  "statusCode": 404
}

// Duplicate tag name
{
  "success": false,
  "message": "Tag with this name already exists",
  "statusCode": 409
}

// Invalid color code
{
  "success": false,
  "message": "Invalid color code format",
  "data": {
    "field": "color",
    "example": "#FF6B6B"
  },
  "statusCode": 400
}

// Tag name too long
{
  "success": false,
  "message": "Tag name must be 50 characters or less",
  "statusCode": 400
}

---

Best Practices

When to Use This Controller

• ✅ Organizing funnels by project/client
• ✅ Filtering funnels in dashboards
• ✅ Campaign-based funnel grouping
• ✅ Multi-user accounts with many funnels

Common Patterns

1. Color coding: Use consistent colors for tag categories
2. Naming conventions: Prefix tags with category (e.g., "Client: ", "Campaign: ")
3. Multi-tagging: Assign multiple tags per funnel for flexibility
4. Archive tags: Use "Archived" tag instead of deleting old funnels

Edge Cases

• Tag deletion with funnels: Funnels lose tag but remain intact
• Duplicate names: Case-sensitive uniqueness check
• Special characters: Allow unicode for international names
• Empty tags: Tags with 0 funnels remain (not auto-deleted)

---

Tag Color Palette

Recommended Colors

Color Name	Hex Code	Use Case
Red	#FF6B6B	Urgent, Important, E-commerce
Blue	#4ECDC4	Lead Gen, Professional, Corporate
Green	#6BCF7F	Active, Successful, Go-to-market
Yellow	#FFD93D	Draft, In Progress, Testing
Purple	#A8E6CF	Webinar, Events, Special
Orange	#FFA07A	Seasonal, Campaigns, Limited
Gray	#CCCCCC	Archived, Inactive, Old
Pink	#FFB6C1	Valentine's, Special Offers

---

Related Documentation

• Funnels Controller: Assigning tags to funnels
• Reporting: Tag-based analytics
• Search/Filters: Using tags for funnel filtering

---

Last Updated: January 2025
API Version: v1
Maintained By: DashClicks Engineering