Frontend Integration Analytics Guide

Analytics Service – Full Feature Set (Current)

The Analytics Service provides aggregated statistics about phishing simulations, user reports, education completions, XP, click tracking, campaigns, and department breakdowns. It is part of the PhishShield microservices backend and powers the Analytics Dashboard requested by the frontend team.

1. Architecture & Data Flow

The Analytics Service does not need to be called directly to record data. It listens to events published by other services via RabbitMQ and maintains a local event store, as well as dedicated tables for users, campaigns, clicks, and simulation sends.

Event Sources

• Accounts Service – publishes user.created, user.updated, and user.deleted on accounts-event-exchange.

  • Analytics mirrors user data into analytics_users for department-based analysis and at-risk user lists.

• Mailing Service (including the former Waves Service) – publishes mailing events on mailing-event-exchange:

  • mailing.send / mailing.schedule for single emails. These events include auth0Id.

  • mailing.batch_send / mailing.batch_schedule for batch sends. Entries include auth0Id, waveId, and emailId.

  • Also publishes wave lifecycle events on waves-event-exchange:

    • wave.created

    • wave.updated

    • wave.completed

  • Analytics stores every individual send in simulation_sends, keyed by emailId, so that click events can be attributed to the correct user and campaign.

• Report Service – publishes report.submitted on report-event-exchange.

  • Analytics counts submitted reports and, via xp.give events, infers confirmed phishing reports.

• Education Service – publishes education.assign and education.completed.

  • Analytics counts false-positive reports, education assignments, and education completions.

• XP Service – publishes xp.give and xp.given on xp-event-exchange.

  • When the reason includes "phishing", Analytics marks the report as confirmed.

  • When the reason includes "compromised", Analytics records a click event as a fallback for cases where the Resend webhook may not have been received.

• Resend Webhook (via API Gateway) – forwards email.clicked events to Analytics' /email-status/create endpoint.

  • The EmailStatusController calls recordClickFromEmailId, which creates a ClickEvent linked to the correct user and campaign using simulation_sends.

All aggregated data is queried via a REST API exposed through the API Gateway.

2. Authentication & Access

• All analytics endpoints are JWT protected.

• Required role: analyst or admin (enforced by the API Gateway's RolesGuard).

• Include the JWT in the Authorization header as Bearer <token>.

3. Base URL

All Analytics endpoints are accessed through the API Gateway:

http(s)://<gateway-host>/api/analytics

For local development:

http://localhost:3001/api/analytics

Adjust the port if your API Gateway runs on a different port.

4. Available Endpoints

4.1 Summary – KPI Cards with Deltas

GET /api/analytics/summary?period=7d|30d|90d

The period parameter is optional and defaults to 30d.

Response

{
  "detectionRate": {
    "value": 40,
    "delta": -5
  },
  "clickRate": {
    "value": 12,
    "delta": 3
  },
  "totalSimulations": {
    "value": 120,
    "delta": 20
  },
  "atRiskUsers": {
    "value": 8,
    "delta": -2
  },
  "trainingCompletion": {
    "value": 55,
    "delta": 10
  }
}

Notes

• value is the current period's metric.

• delta is the percentage change compared to the previous period of equal length.

4.2 Detection Rate & Click Rate Over Time

GET /api/analytics/detection-rate-over-time?period=7d|30d|90d

Returns daily buckets for the requested period.

Response

[
  {
    "date": "2026-08-01",
    "detectionRate": 50,
    "clickRate": 10
  },
  {
    "date": "2026-08-02",
    "detectionRate": 66.67,
    "clickRate": 20
  }
]

4.3 Department Breakdown

GET /api/analytics/by-department?period=7d|30d|90d

Response

[
  {
    "department": "Finance",
    "sent": 30,
    "reported": 12,
    "detectionRate": 42.86,
    "clickRate": 15
  },
  {
    "department": "IT & Security",
    "sent": 20,
    "reported": 5,
    "detectionRate": 60,
    "clickRate": 25
  }
]

Field Definitions

• sent = number of phishing emails sent to users in that department.

• reported = number of reports submitted by users in that department.

• detectionRate = confirmed / reported * 100 if reported > 0.

• clickRate = clicks / sent * 100 if sent > 0.

4.4 At-Risk Users

GET /api/analytics/at-risk-users?period=7d|30d|90d&limit=10

The limit parameter is optional and defaults to 10.

Response

[
  {
    "auth0Id": "auth0|abc123",
    "name": "John Doe",
    "department": "Finance",
    "clickRate": 80,
    "riskLevel": "high"
  }
]

Field Definitions

• clickRate = percentage of simulated emails that the user clicked.

• riskLevel = high if clickRate > 60, otherwise medium.

4.5 Campaign Performance

GET /api/analytics/campaigns

Returns all campaigns (waves) ordered by start date in descending order.

Campaigns with an endDate in the past are automatically marked as completed.

Response

[
  {
    "id": "wave-uuid",
    "name": "Summer Phishing Wave",
    "status": "completed",
    "targetDepartments": [
      "Finance",
      "HR"
    ],
    "startDate": "2026-08-01T09:00:00.000Z",
    "endDate": "2026-08-10T17:00:00.000Z",
    "createdBy": "auth0|admin"
  }
]

4.6 Overview – Legacy / Raw Counts

GET /api/analytics/overview

Returns raw totals for simple counters.

The frontend should prefer /summary for the dashboard KPI cards.

Response

{
  "totalEmailsSent": 120,
  "totalReports": 45,
  "confirmedPhishing": 18,
  "falsePositives": 27,
  "totalXpGiven": 350,
  "educationAssigned": 27,
  "educationCompleted": 15
}

4.7 Report Statistics – Optional Date Range

GET /api/analytics/reports?from=2026-01-01&to=2026-12-31

Both from and to are optional ISO date strings.

Response

{
  "submitted": 45,
  "confirmed": 18,
  "falsePositive": 27,
  "detectionRate": 40
}

4.8 Mailing / Simulation Statistics

GET /api/analytics/mailing?from=2026-01-01&to=2026-12-31

Both from and to are optional ISO date strings.

Response

{
  "totalSent": 120,
  "scheduled": 8
}

4.9 Time Series – Legacy

GET /api/analytics/timeseries?from=2026-08-01&to=2026-08-10

Returns daily counts of reports, emails sent, and XP given.

4.10 Leaderboard – Top Users by XP

GET /api/analytics/leaderboard?limit=5

The limit parameter is optional and defaults to 10.

4.11 Per-User Statistics

GET /api/analytics/users/:auth0Id

Returns analytics for the specified user.

5. Comparison with Original Frontend Specification

The Analytics Service now implements the main features requested by the original frontend specification.

Feature from Specification | Current Status | Notes -- | -- | -- Total Simulations KPI | ✅ Available | /summary → totalSimulations Detection Rate KPI | ✅ Available | /summary → detectionRate Click Rate KPI | ✅ Available | /summary → clickRate (uses Resend webhook + XP fallback) At-Risk Users | ✅ Available | /at-risk-users Training Completion % KPI | ✅ Available | /summary → trainingCompletion KPI Deltas | ✅ Available | /summary returns value and delta Line Chart: Detection Rate Over Time | ✅ Available | /detection-rate-over-time Department Breakdown | ✅ Available | /by-department Campaign Performance Table | ✅ Available | /campaigns (data from waves)

6. Integration Notes

• No polling needed — the frontend should call these endpoints on page load or on user-triggered refresh. Data is updated asynchronously.

• JWT token — use the same Auth0 token and send it with every request.

• Error handling:

  • 401 means the user should be redirected to login.

  • 403 means the authenticated user does not have the required role.

  • 5xx errors should display a generic error message. Backend logs should be checked for details.

• All analytics endpoints are gated at the API Gateway using RolesGuard, requiring either the admin or analyst role.

7. Future Improvements

Although the main dashboard features are now implemented, several enhancements are possible.

7.1 Campaign-Specific Metrics

Extend /campaigns to include aggregate statistics such as:

• Total emails sent.

• Total clicks.

• Total reports.

• Detection rate.

• Click rate.

7.2 More Granular At-Risk Detection

The current at-risk calculation is primarily based on click rate.

Future versions could incorporate:

• Time-to-click.

• Multiple clicks by the same user.

• Number of phishing simulations clicked.

• Historical user behaviour.

• Repeated failures across campaigns.

7.3 Webhook Reliability

Ensure that Resend webhooks are consistently delivered and processed.

The existing XP fallback already provides additional coverage for cases where the Resend webhook is not received.

7.4 Enhanced User-Level Detail

Add an endpoint that provides a user's complete analytics history, including:

• Click history.

• Report history.

• Campaign participation.

• Detection rate over time.

• Education assignments and completions.

• XP history.