Report Service (report-app)
Relevant source files
The following files were used as context for generating this wiki page:The Report Service (report-app) is a NestJS-based microservice responsible for generating and persisting business intelligence reports. It operates within the project's microservice architecture, listening for report generation requests via a NATS message broker. Upon request, it generates a report, saves a record of the generation event to its dedicated PostgreSQL database using Prisma, and returns the report data.
A critical aspect of the current implementation is that the service generates mock data for all report types. It does not currently communicate with other services like order-app or user-app to fetch real data, even though NATS clients for these services are injected. The logic is designed to simulate report generation and persistence.
Sources: apps/report-app/src/report/report.service.ts:46-135, apps/report-app/src/report-app.module.ts:16-30
Architecture and Components
The report-app is a standard NestJS application configured as a microservice. Its main components are the ReportModule, ReportController, and ReportService, all working together to handle NATS messages and manage report data.
Sources: apps/report-app/src/report-app.module.ts, apps/report-app/src/report/report.controller.spec.ts
Module Structure
The application's entry point is the ReportAppModule. It configures the necessary modules for the service to function, including database connectivity, configuration management, and inter-service communication clients.
This diagram shows the module dependencies within the report-app.
The ReportAppModule imports:
- ConfigModule: For environment variable management.
- PrismaModule: Provides the
PrismaServicefor database interactions. - ReportModule: The core feature module containing the application's logic.
The ReportModule itself provides:
- ReportController: Listens for incoming NATS messages.
- ReportService: Contains the business logic for generating reports.
- NATS Clients: Injects
ClientProxyinstances forORDER_SERVICEandUSER_SERVICE, although they are currently unused in the report generation logic.
Sources: apps/report-app/src/report-app.module.ts:9-32, apps/report-app/src/report/report.controller.spec.ts:21-24
Configuration
The service requires a specific database connection string, which is validated at startup.
| Environment Variable | Description | Example |
|---|---|---|
DATABASE_URL_REPORT | The connection URL for the report database. | postgresql://user:pass@localhost:5432/report_db |
Sources: libs/shared/config/env.validation.spec.ts:104-108
Database Schema
The service uses a single table, ReportEntry, to log every report generation event. This acts as an audit trail for all reports created by the system.
Sources: apps/report-app/prisma/schema.prisma
ER Diagram
The following diagram illustrates the ReportEntry schema.
ReportEntry Table
| Field | Type | Description | Attributes |
|---|---|---|---|
id | String | The unique identifier for the report entry. | @id @default(cuid()) |
type | ReportType | The type of report generated. An enum of SALES_SUMMARY, PRODUCT_PERFORMANCE, or USER_COHORT. | |
payload | Json | The JSON object containing the actual report data. | |
fromAt | DateTime | The start date and time for the data included in the report. | |
toAt | DateTime | The end date and time for the data included in the report. | |
createdAt | DateTime | The timestamp when the report entry was created. | @default(now()) |
Sources: apps/report-app/prisma/schema.prisma:10-19
Report Generation Flow
The service exposes its functionality via NATS. A client (e.g., the API Gateway) sends a message with a specific event pattern and a date range payload. The ReportController receives the message, calls the appropriate method in ReportService, which then generates mock data, persists a ReportEntry to the database, and returns the generated data.
Sequence Diagram
This diagram shows the sequence of events for generating a sales summary report.
NATS API
The service listens for messages on the following NATS event patterns. All endpoints expect a DTO with fromAt and toAt date strings.
| Event Pattern | DTO | Response Type | Description |
|---|---|---|---|
EVENTS.REPORT.SALES_SUMMARY | SalesSummaryDto | SalesSummaryResponse | Generates a mock sales summary report with total orders, revenue, and average order value. |
EVENTS.REPORT.PRODUCT_PERF | ProductPerformanceDto | ProductPerformanceResponse | Generates a mock product performance report with sales figures for a list of predefined products. |
EVENTS.REPORT.USER_COHORT | UserCohortDto | UserCohortResponse | Generates a mock user cohort analysis, including new, active, and returning customers. |
Sources: apps/report-app/test/reports.e2e-spec.ts:92-95, 122-125, 158-161
Core Logic (ReportService)
The ReportService contains the primary business logic. Each public method corresponds to a report type.
salesSummary(dto)
- Validation: Throws a
ValidationRpcExceptioniffromAtis aftertoAt. - Data Generation: Creates a hardcoded
SalesSummaryResponseobject. - Persistence: Creates a
ReportEntrywithtype: 'SALES_SUMMARY'and the generated data as thepayload. - Error Handling: Wraps any database errors in a
ValidationRpcException.
Sources: apps/report-app/src/report/report.service.ts:44-67
productPerformance(dto)
- Validation: Throws a
ValidationRpcExceptioniffromAtis aftertoAt. - Data Generation: Creates a hardcoded
ProductPerformanceResponsewith a predefined list of products. - Persistence: Creates a
ReportEntrywithtype: 'PRODUCT_PERFORMANCE'. - Error Handling: Wraps database errors in a
ValidationRpcException.
Sources: apps/report-app/src/report/report.service.ts:74-101
userCohort(dto)
- Validation: Throws a
ValidationRpcExceptioniffromAtis aftertoAt. - Data Generation: Creates a hardcoded
UserCohortResponsewith mock user metrics. - Persistence: Creates a
ReportEntrywithtype: 'USER_COHORT'. - Error Handling: Wraps database errors in a
ValidationRpcException.
Sources: apps/report-app/src/report/report.service.ts:108-135
Error Handling
The service implements a consistent error handling strategy:
- Input Validation: It performs an initial check on the date range. If
new Date(fromAt) > new Date(toAt), it throws aValidationRpcExceptionwith the message "fromAt must be before toAt". - General Exception Wrapping: All report generation logic is wrapped in a
try...catchblock. Any error that occurs, including database errors from Prisma, is caught and re-thrown as aValidationRpcExceptionwith a user-friendly message (e.g., "Failed to generate sales summary").
Sources: apps/report-app/src/report/report.service.ts:45-47, 62-66