Analytics Domain

Provides sales, member, and visitor analytics for the ticketing platform. Covers both online visitors (web traffic) and onsite visitors (physical attendees scanned at gates). Also manages scheduled reports — generated as PDF/CSV and emailed automatically.

Handles:

Dashboard summary — single-call KPI aggregation
Sales analytics — revenue, orders, AOV, breakdowns by group/age/payment/nationality/variant
Member analytics — totals, new members, growth, age & nationality splits
Online visitor analytics — unique visitors, session duration, device, peak time/day
Onsite visitor analytics — gate scan counts, breakdowns by attraction/age/nationality
Event tracking — public pixel-style endpoint for frontend events
Report management — CRUD + generate on-demand or schedule
Report attachments — download generated PDFs, delete stale files

Architecture

graph LR
    Frontend["Admin Frontend"]
    CoreAPI["CoreAPI (Analytics handlers)"]
    DB["Ticketing DB\n(orders, customers, tracking_events)"]
    ReportStore["File Storage\n(generated reports)"]
    EmailService["Email Service"]

    Frontend -->|GET /api/analytics/*| CoreAPI
    Frontend -->|POST /analytics/track| CoreAPI
    CoreAPI --> DB
    CoreAPI --> ReportStore
    CoreAPI -->|scheduled send| EmailService

The report scheduler runs every 30 min and generates any reports whose frequency has elapsed since lastDateSent.

Data Model

erDiagram
    Report {
        uint reportId
        string title
        string type
        string dataOptions
        string frequency
        string emailTo
        string desc
        string format
        bool isDeleted
        string lastDateSent
    }

    ReportAttachment {
        uint reportAttachmentId
        uint reportId
        string title
        string type
        string emailTo
        string attachmentName
        string attachmentPath
        int64 attachmentSize
        string contentType
        bool isEmailSent
        string generatedDate
    }

    Report ||--o{ ReportAttachment : "generates"

Report Types & Frequencies

`type` value	Description
`onsite_visitors`	Onsite gate scan data
`sales`	Revenue and order data
`members`	Customer registration data
`online_visitors`	Web traffic data

`frequency` value	Schedule
`one_time`	Generated once on demand
`daily`	Every 24 hours
`weekly`	Every 7 days
`monthly`	Every 30 days
`quarterly`	Every 90 days
`annual`	Every 365 days

Endpoints

All endpoints require Authorization: Bearer <token> with role ADMIN, SYSADMIN, or MEMBER unless noted.

Dashboard

`GET /api/dashboard`

Single aggregated KPI card summary used by the admin dashboard landing page.

Response 200 — object with all key metrics (total revenue, orders, members, onsite/online visitors for current period vs previous period).

Sales Analytics

All accept optional query params: startDate, endDate, ticketGroupId.

Method	Path	Description
`GET`	`/api/analytics/totalRevenue`	Total revenue for period
`GET`	`/api/analytics/totalOrders`	Total order count
`GET`	`/api/analytics/avgOrderValue`	Average order value
`GET`	`/api/analytics/topSalesProduct`	Top-selling ticket groups
`GET`	`/api/analytics/salesByTicketGroup`	Revenue breakdown per ticket group
`GET`	`/api/analytics/salesByAgeGroup`	Revenue breakdown by buyer age group
`GET`	`/api/analytics/salesByPaymentMethod`	Revenue breakdown by payment method
`GET`	`/api/analytics/salesByNationality`	Revenue breakdown by buyer nationality
`GET`	`/api/analytics/salesByTicketVariant`	Revenue breakdown by ticket variant

Member Analytics

Method	Path	Description
`GET`	`/api/analytics/totalMembers`	Total registered customers
`GET`	`/api/analytics/totalNewMembers`	New members in period
`GET`	`/api/analytics/membersNetGrowth`	Net growth (new - churned)
`GET`	`/api/analytics/membersByAgeGroup`	Member count by age group
`GET`	`/api/analytics/membersByNationality`	Member count by nationality

Online Visitor Analytics

Method	Path	Description
`GET`	`/api/analytics/totalUniqueVisitors`	Unique web visitors
`GET`	`/api/analytics/newVsReturningOnlineVisitors`	New vs returning ratio
`GET`	`/api/analytics/peakTimeAnalysis`	Traffic by hour of day
`GET`	`/api/analytics/peakDayAnalysis`	Traffic by day of week
`GET`	`/api/analytics/averageSessionDuration`	Avg time on site in seconds
`GET`	`/api/analytics/visitorsByDevice`	Breakdown by device type

Event Tracking

`POST /api/analytics/track`

Public endpoint — no auth required. Records a frontend interaction event.

Request

{
  "event": "page_view",
  "page": "/tickets",
  "sessionId": "<uuid>",
  "deviceType": "mobile",
  "timestamp": "2026-06-23T12:00:00Z"
}

Response 200

{ "success": true }

Onsite Visitor Analytics

Method	Path	Description
`GET`	`/api/analytics/totalOnsiteVisitors`	Total gate scans in period
`GET`	`/api/analytics/newVsReturningOnsiteVisitors`	Repeat vs first-time visitors
`GET`	`/api/analytics/averagePeakDayAnalysis`	Average footfall by weekday
`GET`	`/api/analytics/visitorsByAttraction`	Scan count per attraction/ticket group
`GET`	`/api/analytics/visitorsByAgeGroup`	Onsite visitors by age group
`GET`	`/api/analytics/visitorsByNationality`	Onsite visitors by nationality

Reports

`GET /api/reports`

List all non-deleted reports.

Response 200 — array of Report objects.

`GET /api/report`

Get a single report by ?id=<reportId>.

`POST /api/report`

Create a new report config. Does not generate the file immediately — use /report/generate for that.

Request

{
  "title": "Monthly Sales Report",
  "type": "sales",
  "dataOptions": "revenue;orders;avgOrderValue",
  "frequency": "monthly",
  "emailTo": "manager@example.com",
  "desc": "Auto-sent on the 1st of each month",
  "format": "pdf"
}

`PUT /api/report`

Update an existing report. Pass the full object including reportId.

`DELETE /api/report`

Delete a report (soft-delete via isDeleted). Pass ?id=<reportId> or body with reportId.

`POST /api/report/generate`

Trigger immediate generation for a report. Creates a ReportAttachment record and optionally emails it.

Request

{ "reportId": 12 }

`POST /api/report/preview`

Generate a temporary preview without saving an attachment. Returns the file inline.

`GET /api/reports/data-options`

Returns the valid dataOptions keys for each report type.

`GET /api/reports/attachments`

List all generated report attachments.

`GET /api/reports/:id/attachments`

List attachments for a specific report.

`GET /api/report/attachment/:attachmentId/download`

Download a generated report file. Returns the file with appropriate Content-Type.

`DELETE /api/report/attachment`

Delete a specific attachment by ?attachmentId=<id> or body.