Campaign Report & Analysis End-to-End Implementation

Overview

Two new AI-powered campaign-level features that provide insights at the campaign level (aggregated across all calls):

Feature	Purpose	Feature Gate	Visibility
Campaign Report	User behavior insights, preferences, patterns	campaign_report	Button visible to all; full data only with feature enabled
Campaign Analysis	Agent quality metrics, AI verdict, recommendations	admin_analytics	Fully gated not visible without feature

---

Architecture

---

Feature Gating Logic

Campaign Report (campaign_report feature)

Feature assignment flow:

1. SuperAdmin assigns campaign_report to Organization plan
2. Admin assigns campaign_report to Customer user features
3. Customer now sees full report data

What is blurred (data NOT in API response):

• emerging_themes → empty array
• user_intents → empty array
• user_concerns_or_objections → empty array
• behavior_patterns → empty array
• numeric_patterns → empty array
• segments → empty array
• recommendations → empty array

What is shown as preview:

• Stats (total contacts, sufficient/insufficient counts)
• executive_summary truncated to 150 characters
• First 2 key_findings truncated to 80 characters each

Campaign Analysis (admin_analytics feature)

Fully gated at route level the API returns 403 if the user doesn't have admin_analytics. The UI tab is not rendered at all without the feature.

---

API Endpoints (Client Backend)

POST /api/v2/campaigns/:campaignUID/generate-report

Middleware: verifyJwt → requireFeatureAccess("voice_campaign")

Triggers report generation. The route requires basic campaign access, but the response applies data blurring based on campaign_report feature check in the controller.

Response (with feature):

{
  "success": true,
  "message": "Campaign report generated",
  "data": { /* full report */ },
  "fullAccess": true
}

Response (without feature):

{
  "success": true,
  "message": "Campaign report generated",
  "data": { /* blurred report */ },
  "fullAccess": false
}

GET /api/v2/campaigns/:campaignUID/report

Middleware: verifyJwt → requireFeatureAccess("voice_campaign")

Fetches previously generated report. Same blurring logic applies.

POST /api/v2/campaigns/:campaignUID/generate-analysis

Middleware: verifyJwt → requireFeatureAccess("admin_analytics")

Triggers campaign analysis (background). Returns 403 if feature not assigned.

GET /api/v2/campaigns/:campaignUID/analysis

Middleware: verifyJwt → requireFeatureAccess("admin_analytics")

Fetches previously generated analysis. Returns 403 if feature not assigned.

---

MongoDB Schema

CampaignReport Collection

{
  campaign_id: String,       // unique index, matches Campaign.campaignUID
  campaign_name: String,
  generated_at: String,      // ISO datetime
  stats: {
    total_contacts: Number,
    contacts_with_sufficient_messages: Number,
    contacts_with_insufficient_messages: Number,
    contacts_with_conversation_summary: Number
  },
  ai_report: {
    executive_summary: String,
    key_findings: [String],
    emerging_themes: [String],
    user_intents: [String],
    user_concerns_or_objections: [String],
    behavior_patterns: [String],
    numeric_patterns: [String],
    segments: [String],
    recommendations: [String]
  }
}

CampaignAnalysis Collection

{
  campaign_id: String,       // unique index, matches Campaign.campaignUID
  generated_at: String,      // ISO datetime
  participation: {
    total_calls_attempted: Number,
    total_answered: Number,
    calls_with_quality_evaluation: Number,
    evaluability_rate_pct: Number
  },
  quality_metrics: {
    // 12 dimensions, each:
    intent_understanding: { avg_score: Number, pass_rate_pct: Number, evaluated_calls: Number },
    // ...
  },
  ai_verdict: {
    top_issues: [String],
    verdict_summary: String,
    recommended_actions: [String]
  }
}

---

Frontend Integration

History Page (/history)

When a specific campaign is selected, three tabs appear at the top:

Tab	Content	Feature Required
Overview	Existing stats (success rate ring, contact counts, duration, progress bar)	voice_campaign
Campaign Report	CampaignReportSection component shows report inline	Button visible to all; full data needs campaign_report
Campaign Analysis	CampaignAnalysisSection component shows analysis inline	Tab only renders if admin_analytics enabled

Campaigns Page (/campaigns)

In the Campaign Details modal, a tabbed section at the bottom shows:

Tab	Content	Feature Required
Report	CampaignReportSection (compact mode)	Always shown; data blurred without campaign_report
Analysis	CampaignAnalysisSection (compact mode)	Only shown if admin_analytics enabled

---

Files Changed

Client Backend (backend/client_backend/)

File	Change	Purpose
src/types/index.ts	Modified	Added campaign_report to AVAILABLE_FEATURES and FEATURE_MAP
src/models/CampaignReport.ts	New	Mongoose model for CampaignReport collection
src/models/CampaignAnalysis.ts	New	Mongoose model for CampaignAnalysis collection
src/controllers/campaignAnalytics.controller.ts	New	4 endpoints + feature-gated blurring logic
src/routes/campaignAnalytics.routes.ts	New	Route definitions with middleware
src/app.ts	Modified	Registered new route module

Analysis Backend (backend/Analysis/)

File	Change	Purpose
src/orchestration/report_orchestrator.py	New/Modified	Report generation pipeline with on-the-fly summary generation
src/orchestration/campaign_orchestrator.py	New	Quality analysis pipeline
src/pipeline/report_generator.py	New	Batched LLM report generation
src/pipeline/campaign_analysis.py	New	Metric aggregation + AI verdict
src/pipeline/quality_analysis.py	New	Per-contact quality evaluation (12 dims)
src/routes/report_routes.py	New	Report endpoint
src/routes/campaign_routes.py	New	Analysis endpoint
src/schemas/report_schema.py	New	Pydantic models
src/schemas/campaign_schema.py	New	Pydantic models
src/services/openai_service.py	Modified	Added IST time context
app.py	Modified	Registered routers

Frontend (app/)

File	Change	Purpose
src/lib/features.ts	Modified	Added CAMPAIGN_REPORT feature constant + UI_FEATURE_MAP
src/services/campaign.service.ts	Modified	Added 4 API methods
src/components/campaigns/CampaignReportSection.tsx	New	Reusable report display (inline, not modal)
src/components/campaigns/CampaignAnalysisSection.tsx	New	Reusable analysis display (inline, not modal)
src/pages/customer/HistoryPage.tsx	Modified	Added top-level tabs: Overview / Report / Analysis
src/pages/customer/CampaignsPage.tsx	Modified	Added report/analysis in Campaign Detail Modal

---

Data Flow: Report Generation (Detailed)

---

Enabling Features (Admin Guide)

As SuperAdmin:

1. Go to Organization Management
2. Edit the organization's plan features
3. Add campaign_report and/or admin_analytics

As Organization Admin:

1. Go to Customer Management
2. Edit a customer's features
3. Assign campaign_report and/or admin_analytics from the available org features

Feature Dependencies:

• campaign_report standalone, requires only voice_campaign (for campaign access)
• admin_analytics standalone, used for both token analytics AND campaign analysis