Report System

The AquaGen API report system is a powerful and flexible engine for generating water management reports in multiple formats. This document explains how the report system works and how to use it effectively.

📊 Overview

The report system supports:

• 8 Report Types: Daily, Monthly, Hourly, Granular, Weekly, Summary, Daily Range, Monthly Range
• 26 Service Types: Water, Energy, Level, Quality, Borewell, and more
• 4 Output Formats: HTML, PDF, XLSX, CSV
• Customization: Date ranges, shifts, units, divisions

🗓️ Report Types

1. Daily Report

Purpose: Single day summary with detailed metrics

Use Cases:

• Daily consumption summary
• Compliance reporting
• Shift performance analysis

Example Request:

GET /api/user/report?reportType=daily&reportFormat=pdf&service=water&startDate=09/11/2024

Data Aggregation:

• Hourly breakdowns
• Min, max, average values
• Total consumption
• Shift-wise data (if applicable)

2. Monthly Report

Purpose: Complete month aggregation with trends

Use Cases:

• Monthly billing
• Regulatory compliance
• Trend analysis

Example Request:

GET /api/user/report?reportType=monthly&reportFormat=xlsx&service=energy&startDate=01/11/2024

Data Aggregation:

• Daily summaries for entire month
• Month-to-date totals
• Peak and off-peak analysis
• Comparison with previous periods

3. Hourly Report

Purpose: Hour-by-hour detailed analysis

Use Cases:

• Operational optimization
• Peak hour identification
• Anomaly detection

Example Request:

GET /api/user/report?reportType=hourly&reportFormat=html&service=water&startDate=09/11/2024&endDate=10/11/2024&unitId=unit-123

Data Aggregation:

• Hour-by-hour breakdown
• 5-minute interval averages
• Hourly totals and trends

Time Range Support:

# Custom time range (9 AM to 5 PM)
?startTime=9&endTime=17

4. Granular Report

Purpose: High-resolution 5-minute interval data

Use Cases:

• Troubleshooting
• Detailed analysis
• Pattern recognition

Example Request:

GET /api/user/report?reportType=granular&reportFormat=csv&service=quality&startDate=09/11/2024&endDate=09/11/2024&unitId=unit-123

Data Resolution: 288 readings per day (5-minute intervals)

5. Weekly Report

Purpose: Week-long summary

Use Cases:

• Weekly performance review
• Short-term trend analysis

6. Summary Report

Purpose: Executive summary with key insights

Use Cases:

• Management dashboards
• Quick overview
• KPI tracking

7. Daily Range Report

Purpose: Custom date range with daily aggregation

Example Request:

GET /api/user/report?reportType=daily_range&startDate=01/11/2024&endDate=07/11/2024

8. Monthly Range Report

Purpose: Custom date range with monthly aggregation

Example Request:

GET /api/user/report?reportType=monthly_range&startDate=01/01/2024&endDate=31/10/2024

💧 Service Types

Core Services

1. Water (Flow) Service

ServiceType: water

Measures:

• Water consumption (liters, kiloliters, megaliters)
• Flow rates (L/min, L/hour)
• Source-wise breakdown
• Cumulative totals

Report Features:

• Multiple source tracking
• Sub-category analysis
• Shift-wise consumption
• Trend visualization

Example Data:

Time	Source 1 (KL)	Source 2 (KL)	Total (KL)
00:00-01:00	12.5	8.3	20.8
01:00-02:00	11.2	7.9	19.1
...	...	...	...

2. Energy Service

ServiceType: energy

Measures:

• Power consumption (kWh)
• Peak demand (kW)
• Power factor
• Energy cost estimation

Report Features:

• Time-of-use analysis
• Load curves
• Efficiency metrics
• Cost allocation

3. Level (Stock) Service

ServiceType: level

Measures:

• Water level (meters, feet)
• Tank capacity (%)
• Volume (liters)
• Fill/drain rates

Report Features:

• Multiple tank tracking
• Level trends
• Low-level alerts
• Capacity utilization

4. Quality Service

ServiceType: quality

Measures:

• pH, TDS, COD, BOD, DO
• Temperature, EC, TSS
• Turbidity, chlorine levels
• Custom parameters

Report Features:

• Multi-parameter tracking
• Compliance checking
• Threshold violations
• Quality trends

Example Quality Data:

Parameter	Min	Max	Avg	Unit	Standard
pH	6.8	7.4	7.1	-	6.5-8.5
TDS	320	450	385	mg/L	<500
COD	18	35	26	mg/L	<30

5. Borewell Service

ServiceType: borewell

Measures:

• Groundwater extraction
• Water table depth
• Pump runtime
• Recharge rates

Advanced Services

6. Smart City Service

ServiceType: smart_city

Purpose: Multi-category urban water management

Features:

• Combined water, energy, level reporting
• City-wide dashboard
• Zone-wise analysis
• Infrastructure monitoring

7. Water Balance Service

ServiceType: water_balance

Purpose: Water consumption vs. availability analysis

Metrics:

• Total inflow
• Total outflow
• Balance (surplus/deficit)
• Sustainability index

8. Consolidated Report

ServiceType: consolidated

Purpose: Multi-service consolidated view

Features:

• Water + Energy combined
• Monthly consolidation
• Cross-service analytics

9. Alert Report

ServiceType: alert

Purpose: Alert summary and statistics

Features:

• Alert frequency
• Alert types breakdown
• Resolution times
• Severity distribution

10. Aqua GPT Report

ServiceType: aqua_gpt

Purpose: AI-generated insights and recommendations

Features:

• Automated analysis
• Anomaly detection
• Predictive insights
• Optimization recommendations

Custom Services

• custom_water - Customized water report
• custom_energy - Customized energy report
• custom_level - Customized level report
• custom_quality - Customized quality report
• custom_withdrawal - Groundwater withdrawal

📄 Output Formats

1. HTML Format

Use Case: Web display, printing

Features:

• Responsive design
• Print-optimized CSS
• Charts and graphs
• Interactive tables

Example:

<!DOCTYPE html>
<html>
<head>
    <title>Daily Water Consumption Report</title>
    <style>
        /* Report styling */
    </style>
</head>
<body>
    <header>
        <img src="industry-logo.png" />
        <h1>Daily Water Consumption Report</h1>
    </header>
    <section>
        <table><!-- Data table --></table>
    </section>
</body>
</html>

2. PDF Format

Use Case: Archiving, email distribution

Technology: xhtml2pdf, reportlab

Features:

• Professional formatting
• Page numbering
• Headers and footers
• Charts embedded as images

Generation Process:

3. XLSX (Excel) Format

Use Case: Data analysis, manipulation

Technology: xlsxwriter

Features:

• Multiple worksheets
• Formatted cells
• Formulas and calculations
• Charts (optional)

Example Structure:

Worksheet 1: Summary
- Report metadata
- Total consumption
- Key metrics

Worksheet 2: Hourly Data
- Time | Source 1 | Source 2 | Total

Worksheet 3: Charts
- Consumption trend chart
- Source distribution pie chart

4. CSV Format

Use Case: Data export, integration

Technology: pandas

Features:

• Simple tabular format
• Easy to parse
• Small file size
• Universal compatibility

Example CSV:

Time,Source 1 (KL),Source 2 (KL),Total (KL)
00:00-01:00,12.5,8.3,20.8
01:00-02:00,11.2,7.9,19.1

🎛️ Report Customization

Date Range

All report types support custom date ranges:

# Single day
?startDate=09/11/2024

# Date range
?startDate=01/11/2024&endDate=07/11/2024

Date Format: DD/MM/YYYY

Time Range

Hourly and granular reports support time filtering:

# Business hours only (9 AM to 5 PM)
?startTime=9&endTime=17

# Night shift (10 PM to 6 AM)
?startTime=22&endTime=6

Time Format: 24-hour format (0-23)

Unit Selection

Filter data for specific units/devices:

# Single unit
?unitId=unit-123

# Multiple units
?unitIds=unit-123,unit-456,unit-789

Shift Support

Industries can define shifts for aligned reporting:

# Use shift times
?useShift=true

# Ignore shift times
?useShift=false

Shift Configuration:

• Shift start time (e.g., 06:00)
• Shift end time (e.g., 18:00)
• Multiple shifts per day

Division Factor

Customize unit display by division:

# Display in kiloliters (divide by 1000)
?divisionFactor=1000

# Display in megaliters (divide by 1000000)
?divisionFactor=1000000

🔧 Report Generation Process

End-to-End Flow

Data Aggregation

For Daily Reports:

1. Fetch Data: Get all 5-minute readings for the day
2. Group by Hour: Aggregate into hourly buckets
3. Calculate Metrics: Min, max, avg, total for each hour
4. Daily Totals: Sum across all hours
5. Format Output: Apply units and precision

For Monthly Reports:

1. Fetch Data: Get processed daily data for the month
2. Group by Day: Daily aggregates
3. Calculate Trends: Week-over-week, month-to-date
4. Monthly Totals: Sum across all days
5. Format Output: Tables and charts

For Hourly Reports:

1. Fetch Data: Get 5-minute interval data
2. Group by Hour: Aggregate into hourly buckets
3. Detailed Breakdown: Show sub-hourly patterns
4. Identify Peaks: Find peak consumption hours
5. Format Output: Detailed tables

For Granular Reports:

1. Fetch Data: Get raw 5-minute data
2. Validate Data: Check for gaps and anomalies
3. Calculate Rates: Flow rates, change rates
4. Format Output: High-resolution tables

📊 Report Templates

Template Structure

app/templates/
├── common/           # Shared components
│   ├── header.html
│   ├── footer.html
│   └── styles.css
├── flow/            # Water consumption templates
│   ├── water_consumption_daily_report.html
│   ├── water_consumption_monthly_report.html
│   └── water_consumption_hourly_report.html
├── energy/          # Energy consumption templates
│   ├── energy_daily_report.html
│   └── energy_monthly_report.html
├── level/           # Water level templates
│   ├── level_daily_report.html
│   └── level_monthly_report.html
├── quality/         # Quality templates
│   ├── quality_daily_report.html
│   └── quality_monthly_report.html
└── ...

Template Rendering

Templates use Jinja2 with custom filters:

{% extends "common/base.html" %}

{% block content %}
<h1>{{ industry_name }} - Daily Water Consumption Report</h1>
<p>Date: {{ report_date | date_to_date }}</p>

<table>
  <thead>
    <tr>
      <th>Time</th>
      <th>Consumption (KL)</th>
    </tr>
  </thead>
  <tbody>
    {% for row in data %}
    <tr>
      <td>{{ row.time | date_time_to_time }}</td>
      <td>{{ row.consumption | decimal_format(2) }}</td>
    </tr>
    {% endfor %}
  </tbody>
</table>

<p>Total: {{ total_consumption | decimal_format(2) }} KL</p>
{% endblock %}

🎯 Best Practices

1. Choose the Right Report Type

Need	Recommended Type
Daily operations	Daily Report
Monthly billing	Monthly Report
Troubleshooting	Granular Report
Peak analysis	Hourly Report
Executive summary	Summary Report
Custom period	Daily/Monthly Range

2. Select Appropriate Format

Use Case	Recommended Format
Email distribution	PDF
Web display	HTML
Data analysis	XLSX
System integration	CSV

3. Optimize Date Ranges

• Use specific date ranges to reduce data volume
• For large periods, use monthly aggregation
• For detailed analysis, use granular reports on small date ranges

4. Leverage Caching

Reports can be cached for faster retrieval:

# Same parameters will return cached report
GET /api/user/report?reportType=daily&startDate=08/11/2024

---

Pro Tip

For regular reporting needs, use the Automated Report System to schedule reports via email.

📚 Next Steps

• API Reference - Reports - Complete API documentation
• Report Generation Guide - Step-by-step tutorial
• Service Types - Deep dive into service layer