Backend CSA - Campaign & Content Management System

Backend API untuk Campaign & Content Management System dengan Firebase Cloud Messaging integration dan advanced analytics.

---

📋 Table of Contents

• Features
• Tech Stack
• Database Schema
• API Endpoints
• Installation
• Environment Variables
• Campaign Analytics
• Project Structure

---

✨ Features

Content Management

• Multi-type content (splash, promo, article, banner, floating widget)
• Multi-corporation support (Walanja, Simaya, CIFO)
• File upload & management with MinIO
• CRUD operations for all content types

Campaign Management

• Scheduled notification campaigns
• Firebase Cloud Messaging integration
• Real-time delivery tracking per user
• Comprehensive analytics & reporting
• Status management (pending, completed, failed, cancelled)
• Automatic campaign execution via cron jobs

User Management

• User token management
• Activity tracking (Hotel, Room, Retail, CCTV visits)
• User-level notification delivery tracking

Admin Features

• Admin account management
• API credential management
• System statistics & analytics

Advanced Analytics

• Campaign performance metrics
• Delivery rate tracking
• Error analysis & breakdown
• Timeline visualization data
• Top performing campaigns
• User engagement metrics

---

🛠 Tech Stack

• Runtime: Node.js
• Framework: Express.js
• Database: MySQL (Prisma ORM)
• Storage: MinIO
• Notifications: Firebase Admin SDK
• Authentication: JWT + API Key
• Logger: Winston
• Scheduler: node-cron

---

🗄 Database Schema

Core Models

AppCampaign

Campaign dengan tracking lengkap:

model AppCampaign {
  UUID_ACP            String
  Title_ACP           String
  Content_ACP         String
  Date_ACP            DateTime
  Status_ACP          CampaignStatus
  
  // Analytics fields
  TargetUsers_ACP     Int?
  SentCount_ACP       Int?
  SuccessCount_ACP    Int?
  FailureCount_ACP    Int?
  DeliveryRate_ACP    Float?
  SentAt_ACP          DateTime?
  CompletedAt_ACP     DateTime?
  ErrorMessage_ACP    String?
}

CampaignDelivery

Per-user delivery tracking:

model CampaignDelivery {
  UUID_CD             String
  Campaign_CD         String
  UserID_CD           String
  Token_CD            String
  Status_CD           DeliveryStatus
  SentAt_CD           DateTime?
  DeliveredAt_CD      DateTime?
  FailedAt_CD         DateTime?
  ErrorMessage_CD     String?
  ResponseData_CD     String?
}

AppContent

model AppContent {
  UUID_APC            String
  Title_APC           String
  Content_APC         String
  Type_APC            ContentType
  CorpType_APC        CorpType
  Url_APC             String?
  Filename_APC        String?
  TargetUrl_APC       String?
}

UsersToken

model UsersToken {
  UUID_UT             String
  UserID_UT           String
  Token_UT            String
  UsersActivity       UsersActivity[]
}

Enums

enum CampaignStatus {
  pending
  completed
  failed
  cancelled
}

enum DeliveryStatus {
  pending
  sent
  delivered
  failed
}

enum ContentType {
  splash
  promo
  article
  banner
  floatingWidget
}

enum CorpType {
  walanja
  simaya
  cifo
}

enum ActivityType {
  VisitHotel
  VisitRoom
  VisitRetail
  VisitCCTV
}

---

🔌 API Endpoints

Authentication

All endpoints require x-api-key header (except /api-management/test)

API Management

• GET /api-management/test - Test API connection
• GET /api-management/test/secure - Test secure API (requires API key)
• POST /api-management/token - Create new API token
• DELETE /api-management/token - Delete API token
• GET /api-management/tokens - Get all API tokens

Content Management (CMS)

• POST /cms/content - Create content
• GET /cms/content/:type/:corp - Get contents by type & corp
• PUT /cms/content/:id - Update content
• DELETE /cms/content/:id - Delete content
• GET /cms/stats - Get CMS statistics with charts data

Campaign Management

• POST /campaign-management/setup - Create campaign
• GET /campaign-management/all - Get all campaigns (filterable by status)
• PUT /campaign-management/:id - Update campaign
• DELETE /campaign-management/:id - Cancel campaign
• POST /campaign-management/send - Send notification to specific user
• GET /campaign-management/analytics - Get campaign analytics & metrics
• GET /campaign-management/report/:id - Get detailed campaign report

User Management

• POST /user-management/setup-token - Setup user FCM token
• GET /user-management/get-all - Get all users
• DELETE /user-management/delete - Delete user

---

📊 Campaign Analytics

Analytics Dashboard (GET /campaign-management/analytics)

Comprehensive analytics untuk monitoring campaign performance.

Response Structure:

{
  summary: {
    campaigns: {
      total: 50,
      completed: 40,
      failed: 3,
      pending: 5,
      cancelled: 2,
      successRate: "93.02%",
      avgResponseTime: "5 minutes",
      upcomingCount: 5
    },
    delivery: {
      totalTargetUsers: 5000,
      totalSent: 5000,
      totalDelivered: 4750,
      totalFailed: 250,
      overallDeliveryRate: "95.00%",
      totalDeliveryRecords: 5000
    }
  },
  
  charts: {
    // Pie Chart: Campaign status distribution
    statusDistribution: {
      labels: ["completed", "failed", "pending", "cancelled"],
      data: [40, 3, 5, 2]
    },
    
    // Pie Chart: Delivery status
    deliveryStatusDistribution: {
      labels: ["delivered", "failed", "pending"],
      data: [4750, 250, 0]
    },
    
    // Line Chart: Campaign timeline (30 days)
    campaignTimeline: {
      "2025-11-01": { total: 5, completed: 4, failed: 1 }
    },
    
    // Line Chart: Delivery rate trend
    deliveryRateTrend: {
      labels: ["2025-11-01", "2025-11-02"],
      data: [95.5, 96.2]
    },
    
    // Stacked Bar: Status over time (7 days)
    statusOverTime: { ... }
  },
  
  // Top 10 best performing campaigns
  topPerforming: [
    {
      id: "uuid",
      title: "Campaign Title",
      targetUsers: 100,
      successCount: 98,
      deliveryRate: 98.00
    }
  ],
  
  upcoming: [...],
  recentActivity: [...]
}

Individual Campaign Report (GET /campaign-management/report/:id)

Detailed report untuk campaign spesifik dengan per-user tracking.

Response Structure:

{
  campaign: {
    id: "uuid",
    title: "Campaign Title",
    content: "Content",
    status: "completed",
    scheduledDate: "2025-11-20T10:00:00Z",
    errorMessage: null
  },
  
  metrics: {
    leadTime: "19 hours",              // Campaign preparation time
    executionTime: "5 minutes",         // Actual sending time
    avgDeliveryTime: "2 seconds",       // Avg time to deliver
    isScheduled: false,
    isOverdue: false
  },
  
  delivery: {
    targetUsers: 100,
    sentCount: 100,
    successCount: 95,
    failureCount: 5,
    deliveryRate: "95.00%",
    sentAt: "2025-11-20T10:00:00Z",
    completedAt: "2025-11-20T10:05:00Z",
    
    // Breakdown per status
    statusBreakdown: {
      pending: 0,
      sent: 0,
      delivered: 95,
      failed: 5
    },
    
    // Error analysis
    errorBreakdown: {
      "Invalid token": 3,
      "Token not registered": 2
    }
  },
  
  timeline: {
    created: "2025-11-19T15:00:00Z",
    scheduled: "2025-11-20T10:00:00Z",
    sent: "2025-11-20T10:00:00Z",
    completed: "2025-11-20T10:05:00Z"
  },
  
  // Per-user delivery records (max 100)
  deliveryRecords: {
    total: 100,
    records: [
      {
        UUID_CD: "uuid",
        UserID_CD: "user123",
        Status_CD: "delivered",
        SentAt_CD: "2025-11-20T10:00:01Z",
        DeliveredAt_CD: "2025-11-20T10:00:03Z",
        ErrorMessage_CD: null
      }
    ]
  }
}

Key Metrics:

• Success Rate: (Completed / Total Executed) × 100
• Delivery Rate: (Success Count / Sent Count) × 100
• Lead Time: Time between creation and scheduled date
• Execution Time: Time taken to send all notifications
• Avg Delivery Time: Average time from sent to delivered

---

🚀 Installation

Prerequisites

• Node.js (v16+)
• MySQL Database
• MinIO Server
• Firebase Project with Admin SDK

Setup

1. Clone repository

git clone <repository-url>
cd backend-csa

2. Install dependencies

npm install

3. Configure environment Create .env file:

DATABASE_URL="mysql://user:password@host:port/database?ssl-mode=REQUIRED"
DATABASE_URL_UTILITY="mysql://user:password@host:port/database?ssl-mode=REQUIRED"
X_API_KEY="your-api-key"
AI_API_KEY="your-ai-key"
MINIO_ENDPOINT="storage.example.com"
MINIO_ACCESS_KEY="admin"
MINIO_SECRET_KEY="secret"
JWT_SECRET_KEY="your-jwt-secret"

4. Setup Firebase Place Firebase service account key at:

app/config/serviceAccountKey.json

5. Run migrations

npx prisma migrate deploy --schema=./prisma/schemas/schema.cms.prisma
npx prisma generate --schema=./prisma/schemas/schema.cms.prisma

6. Start server

npm start
# or for development
npm run dev

---

🌍 Environment Variables

Variable	Description
DATABASE_URL	MySQL connection string for CMS database
DATABASE_URL_UTILITY	MySQL connection string for utility database
X_API_KEY	Master API key for authentication
AI_API_KEY	OpenAI API key for AI features
MINIO_ENDPOINT	MinIO server endpoint
MINIO_ACCESS_KEY	MinIO access key
MINIO_SECRET_KEY	MinIO secret key
JWT_SECRET_KEY	JWT signing secret

---

📁 Project Structure

backend-csa/
├── app/
│   ├── config/
│   │   └── serviceAccountKey.json    # Firebase config
│   ├── controllers/
│   │   ├── app.controller.js         # API management
│   │   ├── campaign.controller.js    # Campaign with analytics
│   │   ├── cms.controller.js         # Content management
│   │   ├── users.controller.js       # User management
│   │   └── ...
│   ├── middleware/
│   │   └── middleware.js             # Auth & validation
│   ├── routes/
│   │   ├── app.route.js
│   │   ├── campaign.route.js
│   │   ├── cms.route.js
│   │   ├── users.route.js
│   │   └── ...
│   ├── services/
│   │   ├── firebase.services.js      # FCM with tracking
│   │   ├── minio.services.js         # File storage
│   │   ├── cronjob.services.js       # Campaign scheduler
│   │   ├── logger.services.js        # Winston logger
│   │   └── ...
│   ├── res/
│   │   └── responses.js              # Response helpers
│   └── static/
│       └── prefix.js                 # Constants
├── prisma/
│   ├── schemas/
│   │   ├── schema.cms.prisma         # CMS database schema
│   │   └── schema.utility.prisma     # Utility database schema
│   ├── clients/                      # Generated Prisma clients
│   └── migrations/                   # Database migrations
├── backups/                          # Database backups
├── index.js                          # Entry point
├── package.json
└── README.md                         # This file

---

🔒 Security

• All endpoints protected with API key authentication
• JWT token validation for user-specific operations
• Input validation and sanitization
• SQL injection prevention via Prisma ORM
• File upload restrictions and validation

---

📝 API Response Format

Success Response

{
  success: true,
  message: "Operation successful",
  data: { ... }
}

Error Response

{
  success: false,
  message: "Error message",
  error: "Error details"
}

---

🎯 Usage Examples

Create Campaign

POST /campaign-management/setup
Headers: { "x-api-key": "your-api-key" }
Body: {
  "title": "New Campaign",
  "content": "Campaign message",
  "date": "2025-11-30T10:00:00Z"
}

Get Analytics

GET /campaign-management/analytics
Headers: { "x-api-key": "your-api-key" }

Get Campaign Report

GET /campaign-management/report/campaign-uuid
Headers: { "x-api-key": "your-api-key" }

---

🔄 Campaign Flow

1. Create - Setup campaign with schedule
2. Schedule - Cron job monitors scheduled campaigns
3. Execute - Send notifications to all users
4. Track - Record delivery status per user
5. Analyze - View metrics and performance

---

📈 Analytics Features

Campaign Metrics

• Total campaigns by status
• Success/failure rates
• Average response time
• Upcoming campaigns count

Delivery Metrics

• Target users vs actual sent
• Delivery success rate
• Failed delivery analysis
• Per-user tracking

Visualization Data

• Status distribution (pie chart)
• Campaign timeline (line chart)
• Delivery rate trend (line chart)
• Status over time (stacked bar)
• Top performers (bar chart)

---

🛠 Development

Run Migrations

# Create migration
npx prisma migrate dev --schema=./prisma/schemas/schema.cms.prisma --name migration_name

# Apply migration
npx prisma migrate deploy --schema=./prisma/schemas/schema.cms.prisma

# Generate client
npx prisma generate --schema=./prisma/schemas/schema.cms.prisma

View Database

npx prisma studio --schema=./prisma/schemas/schema.cms.prisma

---

📞 Support

For issues or questions, please contact the development team.

---

Version: 2.0.0
Last Updated: November 25, 2025
License: Private