Analytics Module Specification

Purpose

The analytics module implements the Analytics Domain inside the Spring Boot Modulith. It owns dashboards, KPI definitions, report definitions, analytical views, metric snapshots, performance summaries, insight records, CEO briefings, and reporting lineage.

Owned Domain

Analytics owns reporting projections, insight records, dashboard definitions, metric snapshots, and executive briefing records. It consumes source-domain events and read models but does not own or mutate operational source facts.

Owned Aggregates

Aggregate	Responsibility
KPI Definition	KPI name, formula, owner, thresholds, interpretation rules, cadence, and status.
Report Definition	Report purpose, audience, schedule, filters, format, and distribution rules.
Dashboard	Dashboard layout, widgets, audience, filters, and publication status.
Analytical View	Reporting model derived from source facts with lineage and refresh cadence.
Metric Snapshot	Point-in-time metric value, source references, scope, formula version, and timestamp.
Performance Summary	Period or domain summary of performance, risks, and highlights.
Insight Record	Analytical observation with severity, explanation, evidence, confidence, and status.
CEO Briefing	Executive-ready summaries, selected KPIs, risks, decisions required, and follow-up items.

Owned Entities

Dashboard, Dashboard Widget, KPI Definition, Report Definition, Analytical View, Metric Snapshot, Insight Record, Performance Summary, CEO Briefing, and Analytics Subscription.

Owned Value Objects

KpiId, DashboardId, ReportId, MetricValue, MetricUnit, ReportingPeriod, DataFreshness, TrendDirection, ThresholdBand, InsightSeverity, ConfidenceScore, SourceLineage, FormulaVersion, DashboardAudience, ReportCadence, and CurrencyAmount.

Commands

Command	Responsibility
DefineKPI	Create governed KPI definition and formula version.
UpdateKPI	Revise KPI formula, thresholds, or interpretation rules.
PublishDashboard	Approve dashboard for an audience.
DefineReport	Create scheduled or on-demand report definition.
RefreshAnalyticalView	Refresh reporting model from source events or read models.
CreateMetricSnapshot	Calculate point-in-time metric value with lineage.
CreatePerformanceSummary	Summarize period or domain performance.
CreateInsight	Record analytical finding with evidence and severity.
ReviewInsight	Accept, dismiss, resolve, or escalate an insight.
GenerateReport	Generate report for scope and period.
CreateCEOBriefing	Prepare executive briefing from summaries and insights.

Queries

Query	Responsibility
GetKPIDefinitions	Return approved KPI catalogue and formula versions.
GetDashboard	Return dashboard layout, widgets, and data freshness.
GetReportDefinitions	Return report catalogue and cadence.
GetMetricSnapshots	Return metrics by scope, period, and KPI.
GetAnalyticalViews	Return approved reporting model metadata and freshness.
GetInsights	Return insight records by severity, status, and period.
GetPerformanceSummary	Return domain or period performance summary.
GetCEOBriefing	Return executive briefing with source lineage.
GetProcurementPerformance	Return procurement dashboard metrics.
GetDomainAnalytics	Return win/loss, compliance, contract, supplier, funding, or learning analytics views.

Application Services

KPIDefinitionApplicationService, DashboardApplicationService, ReportApplicationService, AnalyticalViewApplicationService, MetricSnapshotApplicationService, PerformanceSummaryApplicationService, InsightApplicationService, CEOBriefingApplicationService, AnalyticsRefreshApplicationService, and AnalyticsSubscriptionApplicationService.

Domain Services

KPIApprovalService, AnalyticalViewRefreshService, MetricSnapshotService, DashboardPublicationService, ReportGenerationService, InsightDetectionService, InsightReviewService, CEOBriefingService, AIExplanationReviewService, and DataLineageService.

Policies

KPI Definition Approval Policy, Analytical View Refresh Policy, Metric Snapshot Policy, Dashboard Publication Policy, Report Generation Policy, Insight Detection Policy, Insight Review Policy, CEO Briefing Policy, AI Explanation Policy, and Data Lineage Policy.

Repositories

KPIDefinitionRepository, DashboardRepository, DashboardWidgetRepository, ReportDefinitionRepository, AnalyticalViewRepository, MetricSnapshotRepository, PerformanceSummaryRepository, InsightRecordRepository, CEOBriefingRepository, SourceLineageRepository, RefreshRunRepository, AnalyticsSubscriptionRepository, and AnalyticsAuditRepository.

Events Published

KPIDefined, KPIUpdated, AnalyticalViewRefreshed, MetricSnapshotCreated, DashboardPublished, ReportGenerated, InsightCreated, InsightReviewed, PerformanceSummaryCreated, and CEOBriefingCreated.

Events Consumed

OrganizationProfileUpdated, ComplianceEvidenceVerified, ProcurementReadinessScoreUpdated, TenderMatchedToOrganization, BidSubmitted, BidOutcomeCaptured, ContractPerformanceUpdated, PaymentRecorded, SupplierTrustUpdated, FundingApplicationStatusChanged, UserProgressUpdated, NotificationAcknowledged, ReasoningCompleted, SubscriptionStarted, InvoicePaid, and AdminActionRecorded.

REST API Responsibility

The module owns API responsibilities for KPI definitions, dashboards, report generation, metric snapshots, analytical views, insights, CEO briefings, procurement performance, win/loss analytics, compliance trends, contract performance, supplier performance, funding analytics, and learning analytics. Final endpoint specs are deferred.

Database Ownership

Analytics owns conceptual persistence for KPI definitions, dashboards, widgets, report definitions, analytical views, metric snapshots, performance summaries, insight records, CEO briefings, source lineage, refresh runs, analytics subscriptions, and analytics audit logs.

Module Dependencies

Allowed dependencies are shared kernel identifiers, identity authorization context, source-domain events, source-domain read models where approved, intelligence explanation support, notification report delivery requests, and future warehouse or projection infrastructure.

Forbidden Dependencies

Analytics must not mutate operational facts, act as a command path for source domains, hide source lineage, replace source-domain ownership, or present AI-generated explanations as source facts.

AIOS Interaction Boundary

AIOS may explain trends, draft insight narratives, and support CEO briefings. Analytics owns metric snapshots, lineage, insight records, review state, and executive briefing publication.

Security And Tenant Rules

• Customer analytics are organization-scoped and must enforce tenant filtering.
• Executive dashboards must expose data freshness and lineage.
• Analytics projections must not leak cross-tenant source facts.
• Insight records must distinguish source facts, analytical interpretation, and AI-assisted explanation.
• Report distribution must respect recipient authorization and Notification preferences.

Test Strategy

Tests must cover KPI approval, formula versioning, view refresh, snapshot lineage, dashboard publication, report generation, insight lifecycle, CEO briefing creation, AI explanation metadata, event consumption, tenant filtering, authorization, and Spring Modulith boundary verification.

Future Microservice Extraction Notes

Analytics can be extracted when projection workloads or warehouse integration mature. Extraction requires event contracts, source lineage guarantees, dashboard/report APIs, tenant-aware analytical storage, and no source-domain mutation path.

Mermaid Component Diagram

flowchart TD
    Api[analytics.api.rest]
    App[analytics.application.service]
    Command[analytics.application.command]
    Query[analytics.application.query]
    Domain[analytics.domain.model]
    Policy[analytics.domain.policy]
    Repo[analytics.infrastructure.persistence]
    Messaging[analytics.infrastructure.messaging]
    Sources[source domain events]
    Intelligence[intelligence explanations]
    Notification[notification report delivery]
    Warehouse[future analytics warehouse]

    Api --> App
    App --> Command
    App --> Query
    App --> Domain
    Domain --> Policy
    App --> Repo
    App --> Messaging
    Messaging --> Sources
    App --> Intelligence
    App --> Notification
    Repo --> Warehouse