Reporting & Analytics

Part of: MPAC SmartPOS Cloud Platform - Product RequirementsVersion: 2.0 Last Updated: 2026-01-28

Overview

The Reporting & Analytics domain provides comprehensive business intelligence and operational insights across the entire SmartPOS platform. It aggregates data from all other domains to deliver real-time dashboards, financial reports, operational metrics, and compliance audit trails. This domain serves as the central analytics hub for system operators, PSP administrators, merchant managers, and store operators to make data-driven decisions.

Purpose & Responsibilities
Dashboard Metrics (Real-time)
Financial Reports
Operational Reports
API Endpoints Summary
Cross-Domain Dependencies

Purpose & Responsibilities

Reporting & Analytics serves as the aggregation and presentation layer for all platform data. The system is designed to:

Provide real-time KPIs for management oversight across all hierarchy levels
Generate detailed financial reports for reconciliation and accounting
Track operational metrics for device health and business performance
Enable compliance auditing and user activity tracking
Support data export for external systems (accounting, BI tools)
Deliver role-based dashboards with appropriate data visibility

Key Features:

Real-time dashboard with sub-second latency for critical metrics
Historical trend analysis with configurable date ranges
Multi-level filtering (PSP → Merchant → Store → Device)
Scheduled report generation and email delivery
Export capabilities (CSV, Excel, PDF)
Audit trail with tamper-proof logging

Data Sources: This domain aggregates data from:

Merchant Hierarchy - Organizational structure and access control
Device Management - Device status and health metrics
Order & Bill - Transaction volumes and order details
Payment Processing - Payment success rates and methods
Payment Gateway - Provider-level settlement data
Customer Management - Customer analytics and engagement
Receipt & Invoice - Digital receipt adoption rates
IAM - User activity and permission audit logs

Dashboard Metrics (Real-time)

Purpose

High-level KPIs for management oversight with real-time updates.

Portal Dashboard Widgets

1. Today's Sales Summary

Provides at-a-glance financial performance for the current day.

Metrics Displayed:

Total transactions count - Number of completed orders
Total revenue - Gross sales amount (before refunds)
Average transaction value - Revenue ÷ transaction count
Payment method breakdown - Pie chart showing distribution:
- QR: 45%
- Credit Card: 35%
- Cash: 20%

Refresh Rate: Every 30 seconds

2. Device Status

Real-time visibility into fleet health and availability.

Metrics Displayed:

Online devices: 35,000 / 40,000 (87.5% uptime)
Offline devices: 5,000
Devices with alerts: 500 (low battery, paper out)
Recent activations: 120 devices today

Alert Conditions:

Offline > 1 hour → Yellow warning
Offline > 6 hours → Red alert
Battery < 20% → Yellow warning
Paper low → Yellow warning

Refresh Rate: Every 60 seconds

3. Top Performing Stores

Ranking of stores by revenue and transaction volume.

Display Format:

Rank | Store Name      | Revenue    | Transactions | Avg Order Value
-----|-----------------|------------|--------------|----------------
  1  | Shibuya Store A | ¥1,250,000 | 523          | ¥2,390
  2  | Shinjuku Store B| ¥980,000   | 412          | ¥2,378
  3  | Ikebukuro Store | ¥875,000   | 390          | ¥2,243

Time Ranges: Today / This Week / This Month

Refresh Rate: Every 5 minutes

4. Transaction Trends

Hourly transaction volume visualization for demand forecasting.

Chart Type: Line chart with dual axes

Primary axis: Transaction count
Secondary axis: Revenue

Features:

Peak hours identification (highlighted zones)
Day-over-day comparison (overlay previous day's curve)
Trend indicators (↑ 15% vs. yesterday)

Time Ranges: Last 24 hours / Last 7 days / Last 30 days

Refresh Rate: Every 5 minutes

5. Payment Method Distribution

Current breakdown of payment method usage.

Visualization: Donut chart with percentages

QR (PayPay, Line Pay, etc.): 45%
Credit Card (Visa, Mastercard, JCB): 35%
Cash: 20%

Drill-down: Click to see provider-level breakdown within each method

Refresh Rate: Every 5 minutes

6. Alerts & Issues

Real-time operational issues requiring attention.

Alert Categories:

Failed payments: 23 (last 1 hour)
Refund requests: 5 (pending approval)
Device offline > 1 hour: 12
Low inventory alerts: 8 stores

Action Items: Each alert links to detailed investigation view or action workflow.

Refresh Rate: Every 30 seconds

Dashboard Filters

All dashboard widgets respect the following global filters:

Filter Options:

Date range selector - Today / Yesterday / Last 7 days / Last 30 days / Custom range
PSP/Merchant/Store filter - Hierarchical dropdown (respects user role permissions)
Payment method filter - Multi-select: QR / Card / Cash
Device status filter - Online / Offline / All

Filter Persistence: Selected filters saved per user session

Financial Reports

Purpose

Detailed financial analysis and reconciliation for accounting and auditing.

Report Types

1. Sales Report

Purpose: Comprehensive revenue analysis with configurable grouping.

Parameters:

Date range: Start date + End date
Group by: Store, Payment Method, Hour/Day/Month
Include refunds: Yes/No toggle

Metrics:

Metric	Description
Total transactions	Count of completed orders
Total revenue (gross)	Sum of all order amounts
Discounts applied	Total discount amount
Tax collected	Sum of tax amounts
Net revenue	Gross - Discounts - Refunds
Refunds	Total refunded amount

Export Formats: CSV, Excel, PDF

Sample Output:

Date       | Store          | Transactions | Gross     | Discounts | Tax    | Net Revenue | Refunds
-----------|----------------|--------------|-----------|-----------|--------|-------------|--------
2026-01-28 | Shibuya Store  | 523          | ¥1,250,000| ¥25,000   | ¥112,500| ¥1,212,500 | ¥12,000
2026-01-28 | Shinjuku Store | 412          | ¥980,000  | ¥18,000   | ¥88,200 | ¥962,000   | ¥0

Generation Time: On-demand (< 10 seconds for 1 month of data)

2. Payment Method Report

Purpose: Analyze performance and reliability of payment methods.

Parameters:

Date range: Start date + End date
Filter by: Payment method type, Provider

Metrics:

Breakdown by provider - Detailed split within each payment method
Transaction count per method - Volume analysis
Average transaction value per method - Spending patterns
Success rate per method - (Successful / Total attempts) × 100
Failed transaction analysis - Error codes and failure reasons

Export Formats: CSV, Excel, PDF

Sample Output:

Payment Method | Provider  | Transactions | Avg Value | Success Rate | Failed Count
---------------|-----------|--------------|-----------|--------------|-------------
QR             | PayPay    | 1,200        | ¥2,450    | 98.5%        | 18
QR             | Line Pay  | 850          | ¥2,380    | 99.2%        | 7
Credit Card    | Visa      | 700          | ¥3,500    | 97.1%        | 20

3. Settlement Report

Purpose: Daily reconciliation between transactions and provider settlements.

Parameters:

Settlement period: Daily / Weekly / Monthly
Provider filter: All / Specific provider

Metrics:

Daily/weekly/monthly settlements - Expected vs. actual amounts
Cash reconciliation - Cash sales vs. cash register balances
Card batch reconciliation - Card transactions vs. acquirer settlements
QR provider settlement matching - Platform records vs. provider statements
Discrepancies and adjustments - Highlighted mismatches with resolution status

Export Formats: CSV, Excel, PDF

Sample Output:

Date       | Provider  | Expected Settlement | Actual Settlement | Discrepancy | Status
-----------|-----------|---------------------|-------------------|-------------|----------
2026-01-27 | PayPay    | ¥5,250,000          | ¥5,250,000        | ¥0          | Matched
2026-01-27 | Visa      | ¥3,480,000          | ¥3,475,000        | -¥5,000     | Investigating

4. Store Performance Report

Purpose: Compare stores to identify top performers and improvement opportunities.

Parameters:

Date range: Start date + End date
Store filter: All / Specific stores
Sort by: Revenue / Transaction volume / AOV

Metrics:

Revenue by store - Total sales per location
Transaction volume - Order count
Average order value - Revenue ÷ transactions
Device utilization - Transactions per device per day
Staff performance - If staff tracking is enabled

Export Formats: CSV, Excel, PDF

5. Tax Report

Purpose: Compliance reporting for tax authorities.

Parameters:

Date range: Start date + End date
Tax rate filter: All / Specific rate

Metrics:

Tax collected by period - Daily/weekly/monthly totals
Tax-exempt transactions - Count and amount
Tax rate breakdown - 10% standard, 8% reduced, 0% exempt
Export for accounting systems - QuickBooks, Freee, Money Forward compatible formats

Export Formats: CSV, Excel, PDF

Sample Output:

Date       | Tax Rate | Taxable Amount | Tax Collected | Exempt Transactions
-----------|----------|----------------|---------------|--------------------
2026-01-28 | 10%      | ¥10,000,000    | ¥1,000,000    | 5 (¥25,000)
2026-01-28 | 8%       | ¥2,000,000     | ¥160,000      | 0

Operational Reports

1. Device Health Report

Purpose: Monitor device fleet health and maintenance needs.

Parameters:

Date range: Start date + End date
Device filter: All / Specific devices / Specific stores

Metrics:

Device online/offline hours - Uptime percentage
Battery level trends - Average battery level over time
Paper consumption - Receipts printed vs. paper roll capacity
Transaction volume per device - Identify underutilized devices
Device errors and alerts - Error codes, frequency, resolution status

Export Formats: CSV, Excel

Sample Output:

Device ID | Store          | Uptime | Avg Battery | Transactions | Alerts
----------|----------------|--------|-------------|--------------|-------
DEV-001   | Shibuya Store  | 98.5%  | 85%         | 523          | 0
DEV-002   | Shinjuku Store | 87.3%  | 45%         | 412          | 2 (Low battery)

2. Customer Analytics

Purpose: Understand customer behavior and engagement.

Parameters:

Date range: Start date + End date
Customer segment filter: New / Repeat / VIP

Metrics:

New customers acquired - First-time customers
Repeat customer rate - % of customers with 2+ visits
Customer lifetime value - Average total spending per customer

Export Formats: CSV, Excel

3. Order Analysis

Purpose: Identify popular products and ordering patterns.

Parameters:

Date range: Start date + End date
Store filter: All / Specific stores

Metrics:

Popular items/products - Top 10 by quantity sold
Order type distribution - Dine-in: 60%, Takeaway: 30%, Delivery: 10%
Average order value trends - Daily/weekly/monthly AOV changes
Peak ordering times - Heatmap of order concentration by hour and day

Export Formats: CSV, Excel

4. Audit & Compliance

Purpose: Track all security-relevant activities for compliance and forensics.

Parameters:

Date range: Start date + End date
User filter: All / Specific user
Action filter: All / Login / Permission change / Refund / Impersonation

Audit Logs:

User activity log - All user actions with timestamps
Permission changes - Role and permission modifications
Device provisioning history - Device activations and deactivations
Refund approvals - Who approved refunds and when
Admin impersonation log - All impersonation sessions with full audit trail

Log Retention: 3 years minimum (configurable)

Export Formats: CSV, Excel, JSON (for SIEM integration)

Sample Output:

Timestamp           | User          | Action            | Target        | IP Address    | Status
--------------------|---------------|-------------------|---------------|---------------|-------
2026-01-28 10:30:00 | admin@psp.com | Impersonate User  | merchant@m.com| 203.0.113.45  | Success
2026-01-28 10:31:15 | admin@psp.com | Approve Refund    | Order-12345   | 203.0.113.45  | Success
2026-01-28 10:32:00 | admin@psp.com | End Impersonation | -             | 203.0.113.45  | Success

API Endpoints Summary

Method	Endpoint	Purpose	Auth Required
GET	`/reports/sales`	Sales report with filters	Yes (Bearer JWT)
GET	`/reports/payment-methods`	Payment method breakdown	Yes (Bearer JWT)
GET	`/reports/settlements`	Settlement history	Yes (Bearer JWT)
GET	`/reports/devices`	Device health report	Yes (Bearer JWT)
GET	`/reports/customers`	Customer analytics	Yes (Bearer JWT)
POST	`/reports/export`	Generate export (CSV/Excel)	Yes (Bearer JWT)
GET	`/dashboard/metrics`	Real-time dashboard data	Yes (Bearer JWT)

Common Query Parameters:

start_date - ISO 8601 format (e.g., 2026-01-01T00:00:00Z)
end_date - ISO 8601 format
merchant_id - Filter by merchant (optional, respects role permissions)
store_id - Filter by store (optional, respects role permissions)
format - Export format: json, csv, excel, pdf

Rate Limits:

Dashboard metrics: 120 requests/minute per user
Report generation: 30 requests/minute per user
Export endpoints: 10 requests/minute per user (exports are resource-intensive)

Response Time SLA:

Dashboard metrics: < 500ms p95
Real-time reports: < 2 seconds p95
Historical reports (1 month): < 10 seconds p95
Export generation: < 30 seconds for typical data volumes

Cross-Domain Dependencies

Data Sources (Inbound Dependencies)

This domain aggregates data from all other domains:

Merchant Hierarchy
- Organizational structure for filtering and access control
- Store metadata for grouping reports
Device Management
- Device status (online/offline)
- Device health metrics (battery, errors)
- Device transaction volumes
Order & Bill
- Transaction counts and amounts
- Order type distributions
- Average order values
Payment Processing
- Payment method usage
- Payment success/failure rates
- Failed transaction error codes
Payment Gateway
- Provider-level settlement data
- Reconciliation records
- Provider response times
Customer Management
- Customer visit patterns
- New vs. repeat customer metrics
- Customer lifetime value
Receipt & Invoice
- Digital receipt adoption rates
- Delivery method preferences
IAM
- User activity logs
- Permission change history
- Impersonation audit trails

Data Consumers (Outbound Dependencies)

This domain provides reports to:

Portal UI (React) - Dashboard widgets and report viewers
External BI tools (e.g., Tableau, Power BI) via API integration
Accounting systems (e.g., QuickBooks, Freee) via export files
Email delivery system for scheduled report distribution

Performance Considerations

Data Aggregation Strategy:

Real-time metrics: Served from Redis cache (30-60 second TTL)
Historical reports: Queried from read replica with time-series optimized indexes
Large exports: Processed asynchronously with job queue (background workers)

Scalability Targets:

Support 400,000+ devices across all merchants
Handle 80M transactions/day in reporting queries
Generate exports for 1M+ transaction datasets within 30 seconds

See Also: Performance & Scalability

Previous: App UpdatesUp: Domain CatalogRelated: Merchant Hierarchy | Performance & Scalability

Reporting & Analytics

Overview

Table of Contents

Purpose & Responsibilities

Dashboard Metrics (Real-time)

Purpose

Portal Dashboard Widgets

1. Today's Sales Summary

2. Device Status

3. Top Performing Stores

4. Transaction Trends

5. Payment Method Distribution

6. Alerts & Issues

Dashboard Filters

Financial Reports

Purpose

Report Types

1. Sales Report

2. Payment Method Report

3. Settlement Report

4. Store Performance Report

5. Tax Report

Operational Reports

1. Device Health Report

2. Customer Analytics

3. Order Analysis

4. Audit & Compliance

API Endpoints Summary

Cross-Domain Dependencies

Data Sources (Inbound Dependencies)

Data Consumers (Outbound Dependencies)

Performance Considerations

Navigation

Reporting & Analytics ​

Overview ​

Table of Contents ​

Purpose & Responsibilities ​

Dashboard Metrics (Real-time) ​

Purpose ​

Portal Dashboard Widgets ​

1. Today's Sales Summary ​

2. Device Status ​

3. Top Performing Stores ​

4. Transaction Trends ​

5. Payment Method Distribution ​

6. Alerts & Issues ​

Dashboard Filters ​

Financial Reports ​

Purpose ​

Report Types ​

1. Sales Report ​

2. Payment Method Report ​

3. Settlement Report ​

4. Store Performance Report ​

5. Tax Report ​

Operational Reports ​

1. Device Health Report ​

2. Customer Analytics ​

3. Order Analysis ​

4. Audit & Compliance ​

API Endpoints Summary ​

Cross-Domain Dependencies ​

Data Sources (Inbound Dependencies) ​

Data Consumers (Outbound Dependencies) ​

Performance Considerations ​

Navigation ​

Reporting & Analytics

Overview

Table of Contents

Purpose & Responsibilities

Dashboard Metrics (Real-time)

Purpose

Portal Dashboard Widgets

1. Today's Sales Summary

2. Device Status

3. Top Performing Stores

4. Transaction Trends

5. Payment Method Distribution

6. Alerts & Issues

Dashboard Filters

Financial Reports

Purpose

Report Types

1. Sales Report

2. Payment Method Report

3. Settlement Report

4. Store Performance Report

5. Tax Report

Operational Reports

1. Device Health Report

2. Customer Analytics

3. Order Analysis

4. Audit & Compliance

API Endpoints Summary

Cross-Domain Dependencies

Data Sources (Inbound Dependencies)

Data Consumers (Outbound Dependencies)

Performance Considerations

Navigation