@rashidee/co2 1.2.5

package/plugin/skills/specgen-spring-jpa-jtehtmx/references/jasper-patterns.md

@@ -0,0 +1,1638 @@
+# Reporting Patterns — JasperReports with JRDesign API (Programmatic Layout)
+
+This reference describes the reporting infrastructure for the spec. Include this content
+in the Reporting section of the generated specification. All code samples must be reproduced
+in the generated spec with full import statements and constructor injection.
+
+The reporting feature provides:
+- **Report Interface** for modules to define and register their own reports
+- **JasperReports JRDesign API** for building report layouts entirely in Java code — no `.jrxml` templates
+- **DTO-based data source** via `JRBeanCollectionDataSource` — no direct DB queries in reports
+- **Multi-format export** — PDF, XLSX, CSV
+- **Report registry** persisted in the database for discoverability
+- **Report parameter forms** rendered via JTE for user input before generation
+- **ReportDesignHelper** utility with static builders for common layout patterns
+
+---
+
+## Architecture Overview
+
+```
+Module                    Shared Reporting Infrastructure
+┌─────────────────────┐         ┌─────────────────────────────────────────┐
+│  StaffReport        │         │  ReportService                          │
+│  implements         │────────►│    compile(JasperDesign → JasperReport) │
+│  ReportDefinition   │         │    fill(JasperReport + DTO Collection)  │
+│                     │         │    export(JasperPrint → PDF/XLSX/CSV)   │
+│  getReportId()      │         │                                         │
+│  getName()          │         │  ReportDesignHelper                     │
+│  getDescription()   │         │    createA4PortraitDesign()             │
+│  getParameters()    │         │    createA4LandscapeDesign()            │
+│  buildDesign(...)   │         │    addField(), createTitleBand(), etc.  │
+│  generateData(...)  │         │                                         │
+│                     │         │  ReportRegistry                         │
+│  DTO: StaffReportDTO│         │    discovers @Component ReportDefinition│
+│  (data source bean) │         │    persists to report table             │
+│                     │         │    provides report lookup               │
+└─────────────────────┘         │                                         │
+                                │  ReportController                       │
+                                │    GET /reports — list all reports      │
+                                │    GET /reports/{id} — parameter form   │
+                                │    POST /reports/{id}/generate — export │
+                                └─────────────────────────────────────────┘
+```
+
+**Data flow:**
+1. User selects a report from the report list page
+2. Report parameter form is rendered (date range, filters, etc.)
+3. User submits parameters → `ReportController` dispatches to the matching `ReportDefinition`
+4. `ReportDefinition.generateData(params)` calls module services to produce a `List<DTO>`
+5. `ReportDefinition.buildDesign(params)` builds a `JasperDesign` programmatically via JRDesign API
+6. `ReportService` compiles `JasperDesign` → `JasperReport`, wraps DTOs in `JRBeanCollectionDataSource`, fills, and exports
+7. The exported file (PDF/XLSX/CSV) is returned as a download response
+
+---
+
+## Maven Dependencies
+
+```xml
+<!-- Reporting (included when Reporting = yes) -->
+<dependency>
+    <groupId>net.sf.jasperreports</groupId>
+    <artifactId>jasperreports</artifactId>
+    <version>7.0.3</version>
+</dependency>
+<dependency>
+    <groupId>net.sf.jasperreports</groupId>
+    <artifactId>jasperreports-fonts</artifactId>
+    <version>7.0.3</version>
+</dependency>
+<!-- PDF export via OpenPDF (JasperReports 7.x default) -->
+<dependency>
+    <groupId>com.github.librepdf</groupId>
+    <artifactId>openpdf</artifactId>
+    <version>2.0.4</version>
+</dependency>
+<!-- XLSX export -->
+<dependency>
+    <groupId>org.apache.poi</groupId>
+    <artifactId>poi-ooxml</artifactId>
+    <version>5.4.1</version>
+</dependency>
+```
+
+> **Note:** JasperReports 7.x uses OpenPDF instead of iText for PDF generation. The
+> `jasperreports` artifact pulls in transitive dependencies, but `openpdf` and `poi-ooxml`
+> should be declared explicitly for version control.
+
+---
+
+## Application Configuration
+
+```yaml
+# [If Reporting = yes] add to application.yml:
+app:
+  reporting:
+    temp-path: ${java.io.tmpdir}/reports # temp directory for export files
+    default-format: PDF                  # PDF, XLSX, CSV
+```
+
+### application-prod.yml overrides
+
+```yaml
+app:
+  reporting:
+    temp-path: ${REPORT_TEMP_PATH:/tmp/reports}
+    default-format: PDF
+```
+
+---
+
+## Package Structure
+
+```
+shared/
+└── reporting/
+    ├── ReportDefinition.java              # Interface for modules to implement
+    ├── ReportParameter.java               # Report parameter descriptor record
+    ├── ReportFormat.java                   # Enum: PDF, XLSX, CSV
+    ├── ReportResult.java                   # Holds generated bytes + metadata
+    ├── ReportDesignHelper.java            # Utility for common JRDesign layout patterns
+    ├── ReportService.java                  # Compile, fill, export orchestrator
+    ├── ReportRegistry.java                 # Auto-discovers and persists report definitions
+    ├── ReportConfig.java                   # Configuration properties binding
+    ├── ReportGenerationException.java      # Runtime exception for report failures
+    ├── ReportEntity.java                   # [If JPA] Database entity for report registry
+    ├── ReportDocument.java                # [If MongoDB] Document for report registry
+    ├── ReportRepository.java              # [If JPA/MongoDB] Spring Data repository
+    ├── page/
+    │   └── ReportPageController.java      # Page controller for report UI
+    ├── fragment/
+    │   └── ReportFragmentController.java  # Fragment controller for htmx updates
+    └── view/
+        ├── ReportListView.java            # View model for report list
+        └── ReportGenerateView.java        # View model for parameter form
+```
+
+---
+
+## Report Definition Interface
+
+Modules implement this interface to define their reports. Each implementation is
+a Spring `@Component` automatically discovered by the `ReportRegistry`.
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+import net.sf.jasperreports.engine.design.JasperDesign;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Contract for domain-defined reports. Each domain module creates one or more
+ * implementations as Spring @Component beans. The ReportRegistry auto-discovers
+ * them at startup and persists their metadata to the database.
+ */
+public interface ReportDefinition {
+
+    /**
+     * Unique identifier for this report (e.g., "staff-allocation-summary").
+     * Used as the report ID in URLs and database records.
+     */
+    String getReportId();
+
+    /**
+     * Human-readable report name displayed in the report list.
+     */
+    String getName();
+
+    /**
+     * Brief description of what this report contains.
+     */
+    String getDescription();
+
+    /**
+     * The domain this report belongs to (e.g., "Staff", "Project").
+     * Used for grouping reports in the UI.
+     */
+    String getDomain();
+
+    /**
+     * Defines the parameters this report accepts (date range, filters, etc.).
+     * The ReportController renders a form based on these parameter descriptors.
+     * Return an empty list if the report takes no parameters.
+     */
+    List<ReportParameter> getParameters();
+
+    /**
+     * Builds the report layout programmatically using the JRDesign API.
+     * This method constructs a JasperDesign with all bands, fields, styles,
+     * and expressions needed for the report. The design is compiled into a
+     * JasperReport by the ReportService.
+     *
+     * @param parameters user-supplied parameter values — allows dynamic layout
+     *                   adjustments based on user input (e.g., hiding columns)
+     * @return a fully configured JasperDesign ready for compilation
+     */
+    JasperDesign buildDesign(Map<String, Object> parameters);
+
+    /**
+     * Executes domain-specific logic to produce the report data as a collection
+     * of DTOs. The returned collection is wrapped in JRBeanCollectionDataSource
+     * by the ReportService.
+     *
+     * @param parameters user-supplied parameter values keyed by parameter name
+     * @return collection of DTO beans to be used as the Jasper data source
+     */
+    Collection<?> generateData(Map<String, Object> parameters);
+}
+```
+
+---
+
+## Report Parameter Descriptor
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+import java.util.List;
+
+/**
+ * Describes a single parameter that a report accepts.
+ * Used by the ReportController to render the parameter input form.
+ *
+ * @param name        parameter key (e.g., "startDate", "departmentId")
+ * @param label       human-readable label for the form field
+ * @param type        input type: TEXT, DATE, NUMBER, SELECT, BOOLEAN
+ * @param required    whether the parameter is mandatory
+ * @param options     for SELECT type: list of allowed values (label-value pairs)
+ * @param defaultValue default value if user doesn't provide one
+ */
+public record ReportParameter(
+        String name,
+        String label,
+        ParameterType type,
+        boolean required,
+        List<Option> options,
+        String defaultValue
+) {
+    public enum ParameterType {
+        TEXT, DATE, NUMBER, SELECT, BOOLEAN
+    }
+
+    public record Option(String label, String value) {}
+
+    public static ReportParameter text(String name, String label, boolean required) {
+        return new ReportParameter(name, label, ParameterType.TEXT, required, List.of(), null);
+    }
+
+    public static ReportParameter date(String name, String label, boolean required) {
+        return new ReportParameter(name, label, ParameterType.DATE, required, List.of(), null);
+    }
+
+    public static ReportParameter number(String name, String label, boolean required) {
+        return new ReportParameter(name, label, ParameterType.NUMBER, required, List.of(), null);
+    }
+
+    public static ReportParameter select(String name, String label, boolean required, List<Option> options) {
+        return new ReportParameter(name, label, ParameterType.SELECT, required, options, null);
+    }
+
+    public static ReportParameter bool(String name, String label, String defaultValue) {
+        return new ReportParameter(name, label, ParameterType.BOOLEAN, false, List.of(), defaultValue);
+    }
+}
+```
+
+---
+
+## Report Format Enum
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+public enum ReportFormat {
+    PDF("application/pdf", ".pdf"),
+    XLSX("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", ".xlsx"),
+    CSV("text/csv", ".csv");
+
+    private final String contentType;
+    private final String extension;
+
+    ReportFormat(String contentType, String extension) {
+        this.contentType = contentType;
+        this.extension = extension;
+    }
+
+    public String getContentType() { return contentType; }
+    public String getExtension() { return extension; }
+}
+```
+
+---
+
+## Report Result Record
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+/**
+ * Holds the generated report output.
+ *
+ * @param data        the exported report bytes
+ * @param format      the export format used
+ * @param fileName    suggested file name for download
+ * @param contentType MIME type for the HTTP response
+ */
+public record ReportResult(
+        byte[] data,
+        ReportFormat format,
+        String fileName,
+        String contentType
+) {
+    public static ReportResult of(byte[] data, ReportFormat format, String reportId) {
+        String fileName = reportId + format.getExtension();
+        return new ReportResult(data, format, fileName, format.getContentType());
+    }
+}
+```
+
+---
+
+## Report Design Helper
+
+Utility class with static builder methods for common JRDesign layout patterns. Module
+report implementations use these helpers to construct their `JasperDesign` without
+repeating boilerplate for page setup, fonts, bands, and element placement.
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+import net.sf.jasperreports.engine.design.JRDesignBand;
+import net.sf.jasperreports.engine.design.JRDesignExpression;
+import net.sf.jasperreports.engine.design.JRDesignField;
+import net.sf.jasperreports.engine.design.JRDesignLine;
+import net.sf.jasperreports.engine.design.JRDesignStaticText;
+import net.sf.jasperreports.engine.design.JRDesignStyle;
+import net.sf.jasperreports.engine.design.JRDesignTextField;
+import net.sf.jasperreports.engine.design.JRDesignVariable;
+import net.sf.jasperreports.engine.design.JasperDesign;
+import net.sf.jasperreports.engine.type.EvaluationTimeType;
+import net.sf.jasperreports.engine.type.HorizontalTextAlignEnum;
+import net.sf.jasperreports.engine.type.VerticalTextAlignEnum;
+
+import java.awt.Color;
+import java.util.List;
+
+/**
+ * Static utility methods for building JasperDesign objects programmatically.
+ * Provides convenient builders for page setup, fields, bands, and styles
+ * so that module-level report implementations stay concise and consistent.
+ */
+public final class ReportDesignHelper {
+
+    private ReportDesignHelper() {
+        // utility class — no instantiation
+    }
+
+    /**
+     * Column definition used by header and detail band builders.
+     *
+     * @param label     display label for the column header
+     * @param fieldName DTO field name (must match the JRDesignField name)
+     * @param width     column width in pixels
+     */
+    public record ColumnDef(String label, String fieldName, int width) {}
+
+    // ── Page Setup ──────────────────────────────────────────────────────
+
+    /**
+     * Create an A4 portrait JasperDesign (595 x 842 pt) with 20pt margins.
+     * Column width = 595 - 20 - 20 = 555.
+     *
+     * @param name report name (used internally by JasperReports)
+     * @return a JasperDesign with portrait page dimensions configured
+     */
+    public static JasperDesign createA4PortraitDesign(String name) {
+        JasperDesign design = new JasperDesign();
+        design.setName(name);
+        design.setPageWidth(595);
+        design.setPageHeight(842);
+        design.setLeftMargin(20);
+        design.setRightMargin(20);
+        design.setTopMargin(20);
+        design.setBottomMargin(20);
+        design.setColumnWidth(555);
+        return design;
+    }
+
+    /**
+     * Create an A4 landscape JasperDesign (842 x 595 pt) with 20pt margins.
+     * Column width = 842 - 20 - 20 = 802.
+     *
+     * @param name report name (used internally by JasperReports)
+     * @return a JasperDesign with landscape page dimensions configured
+     */
+    public static JasperDesign createA4LandscapeDesign(String name) {
+        JasperDesign design = new JasperDesign();
+        design.setName(name);
+        design.setPageWidth(842);
+        design.setPageHeight(595);
+        design.setLeftMargin(20);
+        design.setRightMargin(20);
+        design.setTopMargin(20);
+        design.setBottomMargin(20);
+        design.setColumnWidth(802);
+        return design;
+    }
+
+    // ── Fields ──────────────────────────────────────────────────────────
+
+    /**
+     * Add a field declaration to the design. Field names must match the getter
+     * names on the DTO (JavaBean convention: field "staffNumber" maps to
+     * getStaffNumber()).
+     *
+     * @param design the JasperDesign to add the field to
+     * @param name   field name matching the DTO property
+     * @param type   Java class of the field (e.g., String.class, Integer.class)
+     */
+    public static void addField(JasperDesign design, String name, Class<?> type) {
+        try {
+            JRDesignField field = new JRDesignField();
+            field.setName(name);
+            field.setValueClass(type);
+            design.addField(field);
+        } catch (Exception e) {
+            throw new ReportGenerationException("Failed to add field: " + name, e);
+        }
+    }
+
+    // ── Styles ──────────────────────────────────────────────────────────
+
+    /**
+     * Create a named style and add it to the design.
+     *
+     * @param design   the JasperDesign to register the style with
+     * @param name     unique style name (referenced by elements)
+     * @param fontName font family name (e.g., "SansSerif", "DejaVu Sans")
+     * @param fontSize font size in points
+     * @param bold     whether the font is bold
+     * @return the created JRDesignStyle for further customization if needed
+     */
+    public static JRDesignStyle createStyle(JasperDesign design, String name,
+                                            String fontName, int fontSize, boolean bold) {
+        try {
+            JRDesignStyle style = new JRDesignStyle();
+            style.setName(name);
+            style.setFontName(fontName);
+            style.setFontSize((float) fontSize);
+            style.setBold(bold);
+            design.addStyle(style);
+            return style;
+        } catch (Exception e) {
+            throw new ReportGenerationException("Failed to create style: " + name, e);
+        }
+    }
+
+    // ── Title Band ──────────────────────────────────────────────────────
+
+    /**
+     * Create a title band with a centered title label.
+     *
+     * @param title       the report title text
+     * @param bandHeight  height of the title band in pixels
+     * @param columnWidth full usable column width of the page
+     * @return a JRDesignBand configured as the title band
+     */
+    public static JRDesignBand createTitleBand(String title, int bandHeight, int columnWidth) {
+        JRDesignBand band = new JRDesignBand();
+        band.setHeight(bandHeight);
+
+        JRDesignStaticText titleText = new JRDesignStaticText();
+        titleText.setX(0);
+        titleText.setY(0);
+        titleText.setWidth(columnWidth);
+        titleText.setHeight(bandHeight - 10);
+        titleText.setText(title);
+        titleText.setFontSize(18f);
+        titleText.setBold(true);
+        titleText.setHorizontalTextAlign(HorizontalTextAlignEnum.CENTER);
+        titleText.setVerticalTextAlign(VerticalTextAlignEnum.MIDDLE);
+        band.addElement(titleText);
+
+        // Separator line below title
+        JRDesignLine line = new JRDesignLine();
+        line.setX(0);
+        line.setY(bandHeight - 5);
+        line.setWidth(columnWidth);
+        line.setHeight(1);
+        line.setForecolor(Color.GRAY);
+        band.addElement(line);
+
+        return band;
+    }
+
+    // ── Column Header Band ──────────────────────────────────────────────
+
+    /**
+     * Create a column header band with static text labels for each column.
+     * Headers are rendered with a light gray background and bold font.
+     *
+     * @param columns list of column definitions (label, fieldName, width)
+     * @return a JRDesignBand configured as the column header band
+     */
+    public static JRDesignBand createColumnHeaderBand(List<ColumnDef> columns) {
+        int bandHeight = 30;
+        JRDesignBand band = new JRDesignBand();
+        band.setHeight(bandHeight);
+
+        int xOffset = 0;
+        for (ColumnDef col : columns) {
+            JRDesignStaticText header = new JRDesignStaticText();
+            header.setX(xOffset);
+            header.setY(0);
+            header.setWidth(col.width());
+            header.setHeight(bandHeight);
+            header.setText(col.label());
+            header.setFontSize(10f);
+            header.setBold(true);
+            header.setVerticalTextAlign(VerticalTextAlignEnum.MIDDLE);
+            header.setMode(net.sf.jasperreports.engine.type.ModeEnum.OPAQUE);
+            header.setBackcolor(new Color(0xE8, 0xE8, 0xE8));
+            band.addElement(header);
+
+            xOffset += col.width();
+        }
+
+        return band;
+    }
+
+    // ── Detail Band ─────────────────────────────────────────────────────
+
+    /**
+     * Create a detail band with text fields bound to DTO properties.
+     * Each column renders a $F{fieldName} expression matching the DTO getter.
+     *
+     * @param columns list of column definitions — fieldName must match an addField() call
+     * @return a JRDesignBand configured as the detail band
+     */
+    public static JRDesignBand createDetailBand(List<ColumnDef> columns) {
+        int bandHeight = 25;
+        JRDesignBand band = new JRDesignBand();
+        band.setHeight(bandHeight);
+
+        int xOffset = 0;
+        for (ColumnDef col : columns) {
+            JRDesignTextField textField = new JRDesignTextField();
+            textField.setX(xOffset);
+            textField.setY(0);
+            textField.setWidth(col.width());
+            textField.setHeight(bandHeight);
+            textField.setVerticalTextAlign(VerticalTextAlignEnum.MIDDLE);
+            textField.setBlankWhenNull(true);
+
+            JRDesignExpression expression = new JRDesignExpression();
+            expression.setText("$F{" + col.fieldName() + "}");
+            textField.setExpression(expression);
+
+            band.addElement(textField);
+            xOffset += col.width();
+        }
+
+        return band;
+    }
+
+    // ── Page Footer Band ────────────────────────────────────────────────
+
+    /**
+     * Create a page footer band with "Page X of Y" text.
+     * Uses the built-in PAGE_NUMBER variable with evaluation-time splitting
+     * to display total page count.
+     *
+     * @param columnWidth full usable column width of the page
+     * @return a JRDesignBand configured as the page footer band
+     */
+    public static JRDesignBand createPageFooterBand(int columnWidth) {
+        int bandHeight = 30;
+        JRDesignBand band = new JRDesignBand();
+        band.setHeight(bandHeight);
+
+        // Separator line above footer
+        JRDesignLine line = new JRDesignLine();
+        line.setX(0);
+        line.setY(0);
+        line.setWidth(columnWidth);
+        line.setHeight(1);
+        line.setForecolor(Color.LIGHT_GRAY);
+        band.addElement(line);
+
+        // "Page X" — evaluated per page
+        JRDesignTextField pageCurrentField = new JRDesignTextField();
+        pageCurrentField.setX(0);
+        pageCurrentField.setY(5);
+        pageCurrentField.setWidth(100);
+        pageCurrentField.setHeight(20);
+        pageCurrentField.setVerticalTextAlign(VerticalTextAlignEnum.MIDDLE);
+        pageCurrentField.setFontSize(8f);
+
+        JRDesignExpression currentExpr = new JRDesignExpression();
+        currentExpr.setText("\"Page \" + $V{PAGE_NUMBER}");
+        pageCurrentField.setExpression(currentExpr);
+        band.addElement(pageCurrentField);
+
+        // " of Y" — evaluated at report level (after all pages rendered)
+        JRDesignTextField pageTotalField = new JRDesignTextField();
+        pageTotalField.setX(100);
+        pageTotalField.setY(5);
+        pageTotalField.setWidth(100);
+        pageTotalField.setHeight(20);
+        pageTotalField.setVerticalTextAlign(VerticalTextAlignEnum.MIDDLE);
+        pageTotalField.setFontSize(8f);
+        pageTotalField.setEvaluationTime(EvaluationTimeType.REPORT);
+
+        JRDesignExpression totalExpr = new JRDesignExpression();
+        totalExpr.setText("\" of \" + $V{PAGE_NUMBER}");
+        pageTotalField.setExpression(totalExpr);
+        band.addElement(pageTotalField);
+
+        return band;
+    }
+}
+```
+
+---
+
+## Report Configuration
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+import lombok.Getter;
+import lombok.Setter;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@ConfigurationProperties(prefix = "app.reporting")
+@Getter
+@Setter
+public class ReportConfig {
+
+    private String tempPath = System.getProperty("java.io.tmpdir") + "/reports";
+    private ReportFormat defaultFormat = ReportFormat.PDF;
+}
+```
+
+---
+
+## Report Service
+
+The central orchestrator that compiles `JasperDesign` objects returned by report
+definitions, fills them with DTO collections via `JRBeanCollectionDataSource`, and
+exports to the requested format.
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import net.sf.jasperreports.engine.JRException;
+import net.sf.jasperreports.engine.JasperCompileManager;
+import net.sf.jasperreports.engine.JasperFillManager;
+import net.sf.jasperreports.engine.JasperPrint;
+import net.sf.jasperreports.engine.JasperReport;
+import net.sf.jasperreports.engine.data.JRBeanCollectionDataSource;
+import net.sf.jasperreports.engine.design.JasperDesign;
+import net.sf.jasperreports.engine.export.JRCsvExporter;
+import net.sf.jasperreports.engine.export.ooxml.JRXlsxExporter;
+import net.sf.jasperreports.export.SimpleCsvExporterConfiguration;
+import net.sf.jasperreports.export.SimpleExporterInput;
+import net.sf.jasperreports.export.SimpleOutputStreamExporterOutput;
+import net.sf.jasperreports.export.SimpleXlsxReportConfiguration;
+import net.sf.jasperreports.pdf.JRPdfExporter;
+import org.springframework.stereotype.Service;
+
+import java.io.ByteArrayOutputStream;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class ReportService {
+
+    private final ReportConfig config;
+
+    // Cache compiled JasperReport objects by reportId to avoid re-compilation on every request
+    private final Map<String, JasperReport> compiledCache = new ConcurrentHashMap<>();
+
+    /**
+     * Generate a report using the specified ReportDefinition, user parameters, and format.
+     *
+     * @param definition the report definition (builds design and generates data)
+     * @param parameters user-supplied parameter values
+     * @param format     desired export format (PDF, XLSX, CSV)
+     * @return ReportResult containing the exported bytes and metadata
+     */
+    public ReportResult generate(ReportDefinition definition,
+                                 Map<String, Object> parameters,
+                                 ReportFormat format) {
+        log.info("Generating report [{}] in format [{}]", definition.getReportId(), format);
+
+        // 1. Generate the data from the domain module
+        Collection<?> data = definition.generateData(parameters);
+        log.debug("Report [{}] produced {} data records", definition.getReportId(), data.size());
+
+        // 2. Compile the JasperDesign (cached by reportId)
+        JasperReport jasperReport = compileDesign(definition, parameters);
+
+        // 3. Create the DTO-based data source
+        JRBeanCollectionDataSource dataSource = new JRBeanCollectionDataSource(data);
+
+        // 4. Build Jasper parameters (pass user params + any report-level params)
+        Map<String, Object> jasperParams = new HashMap<>(parameters);
+
+        // 5. Fill the report
+        JasperPrint jasperPrint = fillReport(jasperReport, jasperParams, dataSource);
+
+        // 6. Export to the requested format
+        byte[] exportedBytes = exportReport(jasperPrint, format);
+
+        log.info("Report [{}] generated successfully: {} bytes", definition.getReportId(), exportedBytes.length);
+        return ReportResult.of(exportedBytes, format, definition.getReportId());
+    }
+
+    /**
+     * Compile a JasperDesign into a JasperReport. Results are cached by reportId.
+     * The design is built programmatically by the ReportDefinition — no XML files involved.
+     */
+    private JasperReport compileDesign(ReportDefinition definition,
+                                       Map<String, Object> parameters) {
+        return compiledCache.computeIfAbsent(definition.getReportId(), id -> {
+            try {
+                log.debug("Building and compiling design for report: {}", id);
+                JasperDesign design = definition.buildDesign(parameters);
+                return JasperCompileManager.compileReport(design);
+            } catch (JRException e) {
+                throw new ReportGenerationException("Failed to compile design for report: " + id, e);
+            }
+        });
+    }
+
+    /**
+     * Fill a compiled JasperReport with parameters and data source.
+     */
+    private JasperPrint fillReport(JasperReport report,
+                                   Map<String, Object> parameters,
+                                   JRBeanCollectionDataSource dataSource) {
+        try {
+            return JasperFillManager.fillReport(report, parameters, dataSource);
+        } catch (JRException e) {
+            throw new ReportGenerationException("Failed to fill report", e);
+        }
+    }
+
+    /**
+     * Export JasperPrint to the specified format.
+     */
+    private byte[] exportReport(JasperPrint jasperPrint, ReportFormat format) {
+        try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
+            switch (format) {
+                case PDF -> exportToPdf(jasperPrint, outputStream);
+                case XLSX -> exportToXlsx(jasperPrint, outputStream);
+                case CSV -> exportToCsv(jasperPrint, outputStream);
+            }
+            return outputStream.toByteArray();
+        } catch (Exception e) {
+            throw new ReportGenerationException("Failed to export report as " + format, e);
+        }
+    }
+
+    private void exportToPdf(JasperPrint print, ByteArrayOutputStream out) throws JRException {
+        JRPdfExporter exporter = new JRPdfExporter();
+        exporter.setExporterInput(new SimpleExporterInput(print));
+        exporter.setExporterOutput(new SimpleOutputStreamExporterOutput(out));
+        exporter.exportReport();
+    }
+
+    private void exportToXlsx(JasperPrint print, ByteArrayOutputStream out) throws JRException {
+        JRXlsxExporter exporter = new JRXlsxExporter();
+        exporter.setExporterInput(new SimpleExporterInput(print));
+        exporter.setExporterOutput(new SimpleOutputStreamExporterOutput(out));
+
+        SimpleXlsxReportConfiguration xlsxConfig = new SimpleXlsxReportConfiguration();
+        xlsxConfig.setOnePagePerSheet(false);
+        xlsxConfig.setRemoveEmptySpaceBetweenRows(true);
+        xlsxConfig.setDetectCellType(true);
+        xlsxConfig.setWhitePageBackground(false);
+        exporter.setConfiguration(xlsxConfig);
+
+        exporter.exportReport();
+    }
+
+    private void exportToCsv(JasperPrint print, ByteArrayOutputStream out) throws JRException {
+        JRCsvExporter exporter = new JRCsvExporter();
+        exporter.setExporterInput(new SimpleExporterInput(print));
+        exporter.setExporterOutput(new SimpleOutputStreamExporterOutput(out));
+
+        SimpleCsvExporterConfiguration csvConfig = new SimpleCsvExporterConfiguration();
+        csvConfig.setFieldDelimiter(",");
+        exporter.setConfiguration(csvConfig);
+
+        exporter.exportReport();
+    }
+
+    /**
+     * Evict a cached compiled report by its reportId. Call this when the
+     * buildDesign() logic changes and the cached JasperReport must be rebuilt.
+     * Typically used during development or after deploying updated report logic.
+     *
+     * @param reportId the report identifier to evict from the cache
+     */
+    public void evictReport(String reportId) {
+        compiledCache.remove(reportId);
+        log.info("Evicted cached compiled report: {}", reportId);
+    }
+}
+```
+
+---
+
+## Report Generation Exception
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+public class ReportGenerationException extends RuntimeException {
+
+    public ReportGenerationException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    public ReportGenerationException(String message) {
+        super(message);
+    }
+}
+```
+
+---
+
+## Report Registry
+
+The registry auto-discovers all `ReportDefinition` beans at startup and persists their
+metadata to the database. This allows the report list page to show all available reports
+without scanning components at runtime.
+
+### [If PostgreSQL/MySQL] Report Entity
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.Setter;
+
+@Entity
+@Table(name = "report")
+@Getter
+@Setter
+public class ReportEntity {
+
+    @Id
+    @Column(name = "report_id", length = 100)
+    private String reportId;
+
+    @Column(name = "name", nullable = false, length = 255)
+    private String name;
+
+    @Column(name = "description", length = 500)
+    private String description;
+
+    @Column(name = "domain", nullable = false, length = 100)
+    private String domain;
+
+    @Column(name = "active", nullable = false)
+    private boolean active = true;
+}
+```
+
+### [If PostgreSQL/MySQL] Report Repository
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+
+public interface ReportRepository extends JpaRepository<ReportEntity, String> {
+
+    List<ReportEntity> findByActiveTrue();
+
+    List<ReportEntity> findByDomainAndActiveTrue(String domain);
+}
+```
+
+### [If PostgreSQL/MySQL] Flyway Migration
+
+```sql
+-- V{N}__create_report_table.sql
+CREATE TABLE report (
+    report_id   VARCHAR(100) PRIMARY KEY,
+    name        VARCHAR(255) NOT NULL,
+    description VARCHAR(500),
+    domain      VARCHAR(100) NOT NULL,
+    active      BOOLEAN NOT NULL DEFAULT TRUE
+);
+```
+
+### [If MongoDB] Report Document
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+import lombok.Getter;
+import lombok.Setter;
+import org.springframework.data.annotation.Id;
+import org.springframework.data.mongodb.core.mapping.Document;
+
+@Document(collection = "report")
+@Getter
+@Setter
+public class ReportDocument {
+
+    @Id
+    private String reportId;
+    private String name;
+    private String description;
+    private String domain;
+    private boolean active = true;
+}
+```
+
+### [If MongoDB] Report Repository
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+import org.springframework.data.mongodb.repository.MongoRepository;
+
+import java.util.List;
+
+public interface ReportRepository extends MongoRepository<ReportDocument, String> {
+
+    List<ReportDocument> findByActiveTrue();
+
+    List<ReportDocument> findByDomainAndActiveTrue(String domain);
+}
+```
+
+### Registry Service
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.context.event.ApplicationReadyEvent;
+import org.springframework.context.event.EventListener;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class ReportRegistry {
+
+    private final List<ReportDefinition> reportDefinitions;
+    private final ReportRepository reportRepository;
+
+    // In-memory lookup for fast dispatch during report generation
+    private final Map<String, ReportDefinition> definitionMap = new ConcurrentHashMap<>();
+
+    /**
+     * On application startup, register all ReportDefinition beans in the database
+     * and build the in-memory lookup map.
+     */
+    @EventListener(ApplicationReadyEvent.class)
+    public void registerReports() {
+        log.info("Registering {} report definitions", reportDefinitions.size());
+
+        for (ReportDefinition definition : reportDefinitions) {
+            definitionMap.put(definition.getReportId(), definition);
+
+            // Upsert to database — [If PostgreSQL/MySQL] use ReportEntity,
+            //                       [If MongoDB] use ReportDocument
+            ReportEntity entity = reportRepository.findById(definition.getReportId())
+                    .orElseGet(ReportEntity::new);
+            entity.setReportId(definition.getReportId());
+            entity.setName(definition.getName());
+            entity.setDescription(definition.getDescription());
+            entity.setDomain(definition.getDomain());
+            entity.setActive(true);
+            reportRepository.save(entity);
+
+            log.info("Registered report: [{}] {} ({})",
+                    definition.getReportId(), definition.getName(), definition.getDomain());
+        }
+
+        // Deactivate reports that no longer have a definition
+        List<ReportEntity> allReports = reportRepository.findAll();
+        for (ReportEntity entity : allReports) {
+            if (!definitionMap.containsKey(entity.getReportId())) {
+                entity.setActive(false);
+                reportRepository.save(entity);
+                log.info("Deactivated report: [{}] (no definition found)", entity.getReportId());
+            }
+        }
+    }
+
+    /**
+     * Get a ReportDefinition by its ID for report generation.
+     */
+    public Optional<ReportDefinition> getDefinition(String reportId) {
+        return Optional.ofNullable(definitionMap.get(reportId));
+    }
+
+    /**
+     * List all active reports from the database.
+     */
+    public List<ReportEntity> listActiveReports() {
+        return reportRepository.findByActiveTrue();
+    }
+
+    /**
+     * List active reports for a specific domain.
+     */
+    public List<ReportEntity> listReportsByDomain(String domain) {
+        return reportRepository.findByDomainAndActiveTrue(domain);
+    }
+}
+```
+
+---
+
+## Report Page Controller
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting.page;
+
+import {{BASE_PACKAGE}}.shared.reporting.ReportDefinition;
+import {{BASE_PACKAGE}}.shared.reporting.ReportFormat;
+import {{BASE_PACKAGE}}.shared.reporting.ReportRegistry;
+import {{BASE_PACKAGE}}.shared.reporting.ReportResult;
+import {{BASE_PACKAGE}}.shared.reporting.ReportService;
+import {{BASE_PACKAGE}}.shared.reporting.view.ReportGenerateView;
+import {{BASE_PACKAGE}}.shared.reporting.view.ReportListView;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.servlet.ModelAndView;
+
+import java.util.Map;
+
+@Controller
+@RequestMapping("/reports")
+@PreAuthorize("isAuthenticated()")
+@RequiredArgsConstructor
+@Slf4j
+public class ReportPageController {
+
+    private final ReportRegistry reportRegistry;
+    private final ReportService reportService;
+
+    /**
+     * List all available reports grouped by domain.
+     */
+    @GetMapping
+    public ModelAndView listReports() {
+        var reports = reportRegistry.listActiveReports();
+        var view = ReportListView.from(reports);
+        return new ModelAndView("shared/reporting/page/list", Map.of("view", view));
+    }
+
+    /**
+     * Show the parameter form for a specific report.
+     */
+    @GetMapping("/{reportId}")
+    public ModelAndView showReportForm(@PathVariable String reportId) {
+        var definition = reportRegistry.getDefinition(reportId)
+                .orElseThrow(() -> new IllegalArgumentException("Report not found: " + reportId));
+        var view = ReportGenerateView.from(definition);
+        return new ModelAndView("shared/reporting/page/generate", Map.of("view", view));
+    }
+
+    /**
+     * Generate and download the report.
+     */
+    @PostMapping("/{reportId}/generate")
+    public ResponseEntity<byte[]> generateReport(
+            @PathVariable String reportId,
+            @RequestParam Map<String, Object> parameters,
+            @RequestParam(defaultValue = "PDF") ReportFormat format) {
+
+        var definition = reportRegistry.getDefinition(reportId)
+                .orElseThrow(() -> new IllegalArgumentException("Report not found: " + reportId));
+
+        ReportResult result = reportService.generate(definition, parameters, format);
+
+        return ResponseEntity.ok()
+                .contentType(MediaType.parseMediaType(result.contentType()))
+                .header(HttpHeaders.CONTENT_DISPOSITION,
+                        "attachment; filename=\"" + result.fileName() + "\"")
+                .body(result.data());
+    }
+}
+```
+
+---
+
+## Report Fragment Controller
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting.fragment;
+
+import {{BASE_PACKAGE}}.shared.reporting.ReportRegistry;
+import {{BASE_PACKAGE}}.shared.reporting.view.ReportGenerateView;
+import {{BASE_PACKAGE}}.shared.reporting.view.ReportListView;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.servlet.ModelAndView;
+
+import java.util.Map;
+
+@Controller
+@RequestMapping("/reports/fragments")
+@PreAuthorize("isAuthenticated()")
+@RequiredArgsConstructor
+@Slf4j
+public class ReportFragmentController {
+
+    private final ReportRegistry reportRegistry;
+
+    /**
+     * htmx fragment: report list content (replaces #content-area without full page load).
+     */
+    @GetMapping("/list")
+    public ModelAndView listReportsFragment() {
+        var reports = reportRegistry.listActiveReports();
+        var view = ReportListView.from(reports);
+        return new ModelAndView("shared/reporting/fragment/list", Map.of("view", view));
+    }
+
+    /**
+     * htmx fragment: report parameter form (replaces #content-area without full page load).
+     */
+    @GetMapping("/{reportId}")
+    public ModelAndView showReportFormFragment(@PathVariable String reportId) {
+        var definition = reportRegistry.getDefinition(reportId)
+                .orElseThrow(() -> new IllegalArgumentException("Report not found: " + reportId));
+        var view = ReportGenerateView.from(definition);
+        return new ModelAndView("shared/reporting/fragment/generate", Map.of("view", view));
+    }
+}
+```
+
+---
+
+## Report View Models
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting.view;
+
+import {{BASE_PACKAGE}}.shared.reporting.ReportEntity;
+import lombok.Getter;
+import lombok.Setter;
+
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+@Getter
+@Setter
+public class ReportListView {
+
+    private Map<String, List<ReportEntry>> reportsByDomain;
+    private int totalReports;
+
+    public record ReportEntry(String reportId, String name, String description, String domain) {}
+
+    public static ReportListView from(List<ReportEntity> entities) {
+        var view = new ReportListView();
+        view.totalReports = entities.size();
+        view.reportsByDomain = entities.stream()
+                .map(e -> new ReportEntry(e.getReportId(), e.getName(), e.getDescription(), e.getDomain()))
+                .collect(Collectors.groupingBy(ReportEntry::domain));
+        return view;
+    }
+}
+```
+
+```java
+package {{BASE_PACKAGE}}.shared.reporting.view;
+
+import {{BASE_PACKAGE}}.shared.reporting.ReportDefinition;
+import {{BASE_PACKAGE}}.shared.reporting.ReportParameter;
+import lombok.Getter;
+import lombok.Setter;
+
+import java.util.List;
+
+@Getter
+@Setter
+public class ReportGenerateView {
+
+    private String reportId;
+    private String name;
+    private String description;
+    private String domain;
+    private List<ReportParameter> parameters;
+
+    public static ReportGenerateView from(ReportDefinition definition) {
+        var view = new ReportGenerateView();
+        view.reportId = definition.getReportId();
+        view.name = definition.getName();
+        view.description = definition.getDescription();
+        view.domain = definition.getDomain();
+        view.parameters = definition.getParameters();
+        return view;
+    }
+}
+```
+
+---
+
+## JTE Templates
+
+### Report List Page
+
+```html
+@import {{BASE_PACKAGE}}.shared.reporting.view.ReportListView
+@import {{BASE_PACKAGE}}.shared.reporting.view.ReportListView.ReportEntry
+
+@param ReportListView view
+
+<!-- Breadcrumb -->
+<div class="mb-6">
+    <nav class="flex" aria-label="Breadcrumb">
+        <ol class="inline-flex items-center space-x-1">
+            <li><a href="/home" hx-get="/home/fragments/content" hx-target="#content-area"
+                   class="text-gray-500 hover:text-gray-700">Home</a></li>
+            <li class="text-gray-400">/</li>
+            <li class="text-gray-900 font-medium">Reports</li>
+        </ol>
+    </nav>
+</div>
+
+<h1 class="text-2xl font-bold mb-6">Reports (${view.getTotalReports()})</h1>
+
+@for(var entry : view.getReportsByDomain().entrySet())
+    <div class="mb-8">
+        <h2 class="text-lg font-semibold text-gray-700 mb-4">${entry.getKey()}</h2>
+        <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+            @for(ReportEntry report : entry.getValue())
+                <div class="bg-white rounded-lg shadow p-6 hover:shadow-md transition-shadow">
+                    <h3 class="text-base font-semibold text-gray-900 mb-2">${report.name()}</h3>
+                    <p class="text-sm text-gray-600 mb-4">${report.description()}</p>
+                    <a href="/reports/${report.reportId()}"
+                       hx-get="/reports/fragments/${report.reportId()}"
+                       hx-target="#content-area"
+                       class="inline-flex items-center text-sm font-medium text-indigo-600 hover:text-indigo-800">
+                        Generate Report →
+                    </a>
+                </div>
+            @endfor
+        </div>
+    </div>
+@endfor
+```
+
+### Report Parameter Form Page
+
+```html
+@import {{BASE_PACKAGE}}.shared.reporting.view.ReportGenerateView
+@import {{BASE_PACKAGE}}.shared.reporting.ReportParameter
+
+@param ReportGenerateView view
+
+<!-- Breadcrumb -->
+<div class="mb-6">
+    <nav class="flex" aria-label="Breadcrumb">
+        <ol class="inline-flex items-center space-x-1">
+            <li><a href="/home" hx-get="/home/fragments/content" hx-target="#content-area"
+                   class="text-gray-500 hover:text-gray-700">Home</a></li>
+            <li class="text-gray-400">/</li>
+            <li><a href="/reports" hx-get="/reports/fragments/list" hx-target="#content-area"
+                   class="text-gray-500 hover:text-gray-700">Reports</a></li>
+            <li class="text-gray-400">/</li>
+            <li class="text-gray-900 font-medium">${view.getName()}</li>
+        </ol>
+    </nav>
+</div>
+
+<div class="max-w-2xl">
+    <h1 class="text-2xl font-bold mb-2">${view.getName()}</h1>
+    <p class="text-gray-600 mb-6">${view.getDescription()}</p>
+
+    <form action="/reports/${view.getReportId()}/generate" method="post"
+          class="bg-white rounded-lg shadow p-6 space-y-6">
+
+        @for(ReportParameter param : view.getParameters())
+            <div>
+                <label for="${param.name()}"
+                       class="block text-sm font-medium text-gray-700 mb-1">
+                    ${param.label()}
+                    @if(param.required())
+                        <span class="text-red-500">*</span>
+                    @endif
+                </label>
+
+                @if(param.type() == ReportParameter.ParameterType.TEXT)
+                    <input type="text" id="${param.name()}" name="${param.name()}"
+                           value="${param.defaultValue() != null ? param.defaultValue() : ""}"
+                           class="w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500"
+                           ${ param.required() ? "required" : "" }>
+                @elseif(param.type() == ReportParameter.ParameterType.DATE)
+                    <input type="date" id="${param.name()}" name="${param.name()}"
+                           value="${param.defaultValue() != null ? param.defaultValue() : ""}"
+                           class="w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500"
+                           ${ param.required() ? "required" : "" }>
+                @elseif(param.type() == ReportParameter.ParameterType.NUMBER)
+                    <input type="number" id="${param.name()}" name="${param.name()}"
+                           value="${param.defaultValue() != null ? param.defaultValue() : ""}"
+                           class="w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500"
+                           ${ param.required() ? "required" : "" }>
+                @elseif(param.type() == ReportParameter.ParameterType.SELECT)
+                    <select id="${param.name()}" name="${param.name()}"
+                            class="w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500"
+                            ${ param.required() ? "required" : "" }>
+                        <option value="">-- Select --</option>
+                        @for(var option : param.options())
+                            <option value="${option.value()}">${option.label()}</option>
+                        @endfor
+                    </select>
+                @elseif(param.type() == ReportParameter.ParameterType.BOOLEAN)
+                    <div class="flex items-center" x-data="{ checked: ${param.defaultValue() != null ? param.defaultValue() : "false"} }">
+                        <input type="hidden" name="${param.name()}" :value="checked">
+                        <button type="button" @click="checked = !checked"
+                                :class="checked ? 'bg-indigo-600' : 'bg-gray-200'"
+                                class="relative inline-flex h-6 w-11 items-center rounded-full transition-colors">
+                            <span :class="checked ? 'translate-x-6' : 'translate-x-1'"
+                                  class="inline-block h-4 w-4 rounded-full bg-white transition-transform"></span>
+                        </button>
+                    </div>
+                @endif
+            </div>
+        @endfor
+
+        <!-- Export Format Selection -->
+        <div>
+            <label class="block text-sm font-medium text-gray-700 mb-1">Export Format</label>
+            <div class="flex space-x-4">
+                <label class="inline-flex items-center">
+                    <input type="radio" name="format" value="PDF" checked
+                           class="text-indigo-600 focus:ring-indigo-500">
+                    <span class="ml-2 text-sm text-gray-700">PDF</span>
+                </label>
+                <label class="inline-flex items-center">
+                    <input type="radio" name="format" value="XLSX"
+                           class="text-indigo-600 focus:ring-indigo-500">
+                    <span class="ml-2 text-sm text-gray-700">Excel (XLSX)</span>
+                </label>
+                <label class="inline-flex items-center">
+                    <input type="radio" name="format" value="CSV"
+                           class="text-indigo-600 focus:ring-indigo-500">
+                    <span class="ml-2 text-sm text-gray-700">CSV</span>
+                </label>
+            </div>
+        </div>
+
+        <!-- Action Buttons -->
+        <div class="flex justify-end space-x-3 pt-4 border-t">
+            <a href="/reports"
+               hx-get="/reports/fragments/list"
+               hx-target="#content-area"
+               class="px-4 py-2 text-sm font-medium text-gray-700 bg-gray-100 rounded-md hover:bg-gray-200">
+                Cancel
+            </a>
+            <button type="submit"
+                    class="px-4 py-2 text-sm font-medium text-white bg-indigo-600 rounded-md hover:bg-indigo-700">
+                Generate Report
+            </button>
+        </div>
+    </form>
+</div>
+```
+
+---
+
+## Module Integration — Sample Report Implementation
+
+Each module creates `@Component` classes implementing `ReportDefinition` to register
+their reports. The implementation calls module services (never repositories directly) to
+produce DTO collections, and builds the report layout programmatically using the
+JRDesign API (with help from `ReportDesignHelper`).
+
+### Sample: Staff Allocation Summary Report
+
+```java
+package {{BASE_PACKAGE}}.staff.internal;
+
+import {{BASE_PACKAGE}}.shared.reporting.ReportDefinition;
+import {{BASE_PACKAGE}}.shared.reporting.ReportDesignHelper;
+import {{BASE_PACKAGE}}.shared.reporting.ReportDesignHelper.ColumnDef;
+import {{BASE_PACKAGE}}.shared.reporting.ReportGenerationException;
+import {{BASE_PACKAGE}}.shared.reporting.ReportParameter;
+import {{BASE_PACKAGE}}.staff.StaffService;
+import lombok.RequiredArgsConstructor;
+import net.sf.jasperreports.engine.design.JasperDesign;
+import org.springframework.stereotype.Component;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Staff Allocation Summary report — lists all staff with their current
+ * allocation status, department, and position.
+ *
+ * Data source: StaffReportDTO (flat DTO projected from Staff entity/document).
+ * Layout: built programmatically via JRDesign API — no .jrxml template.
+ */
+@Component
+@RequiredArgsConstructor
+public class StaffAllocationSummaryReport implements ReportDefinition {
+
+    private final StaffService staffService;
+
+    @Override
+    public String getReportId() {
+        return "staff-allocation-summary";
+    }
+
+    @Override
+    public String getName() {
+        return "Staff Allocation Summary";
+    }
+
+    @Override
+    public String getDescription() {
+        return "Lists all staff members with their department, position, and current allocation status.";
+    }
+
+    @Override
+    public String getDomain() {
+        return "Staff";
+    }
+
+    @Override
+    public List<ReportParameter> getParameters() {
+        return List.of(
+                ReportParameter.select("departmentId", "Department", false,
+                        List.of(
+                                new ReportParameter.Option("All Departments", ""),
+                                new ReportParameter.Option("Software Engineering", "dept-se"),
+                                new ReportParameter.Option("Quality Assurance", "dept-qa")
+                        )),
+                ReportParameter.select("allocationStatus", "Allocation Status", false,
+                        List.of(
+                                new ReportParameter.Option("All", ""),
+                                new ReportParameter.Option("Available", "AVAILABLE"),
+                                new ReportParameter.Option("Allocated", "ALLOCATED")
+                        ))
+        );
+    }
+
+    @Override
+    public JasperDesign buildDesign(Map<String, Object> parameters) {
+        try {
+            // 1. Create landscape A4 page
+            JasperDesign design = ReportDesignHelper.createA4LandscapeDesign("staff-allocation-summary");
+
+            // 2. Declare fields — names must match StaffReportDTO getter names
+            ReportDesignHelper.addField(design, "staffNumber", String.class);
+            ReportDesignHelper.addField(design, "fullName", String.class);
+            ReportDesignHelper.addField(design, "email", String.class);
+            ReportDesignHelper.addField(design, "departmentName", String.class);
+            ReportDesignHelper.addField(design, "positionName", String.class);
+            ReportDesignHelper.addField(design, "allocationStatus", String.class);
+            ReportDesignHelper.addField(design, "allocationPercentage", String.class);
+
+            // 3. Define column layout
+            List<ColumnDef> columns = List.of(
+                    new ColumnDef("Staff No.", "staffNumber", 80),
+                    new ColumnDef("Full Name", "fullName", 150),
+                    new ColumnDef("Email", "email", 170),
+                    new ColumnDef("Department", "departmentName", 130),
+                    new ColumnDef("Position", "positionName", 100),
+                    new ColumnDef("Status", "allocationStatus", 80),
+                    new ColumnDef("Allocation %", "allocationPercentage", 92)
+            );
+
+            // 4. Build title band
+            design.setTitle(ReportDesignHelper.createTitleBand(
+                    "Staff Allocation Summary", 50, design.getColumnWidth()));
+
+            // 5. Build column header band
+            design.setColumnHeader(ReportDesignHelper.createColumnHeaderBand(columns));
+
+            // 6. Build detail band
+            design.setDetail(ReportDesignHelper.createDetailBand(columns));
+
+            // 7. Build page footer with "Page X of Y"
+            design.setPageFooter(ReportDesignHelper.createPageFooterBand(design.getColumnWidth()));
+
+            return design;
+        } catch (Exception e) {
+            throw new ReportGenerationException(
+                    "Failed to build design for report: staff-allocation-summary", e);
+        }
+    }
+
+    @Override
+    public Collection<?> generateData(Map<String, Object> parameters) {
+        String departmentId = (String) parameters.getOrDefault("departmentId", "");
+        String allocationStatus = (String) parameters.getOrDefault("allocationStatus", "");
+
+        // Call domain service to get filtered data as DTOs
+        // The service returns List<StaffReportDTO> — flat DTO suitable for Jasper
+        return staffService.getStaffForReport(departmentId, allocationStatus);
+    }
+}
+```
+
+---
+
+## Sample Report DTO
+
+```java
+package {{BASE_PACKAGE}}.staff.internal;
+
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * Flat DTO used as the data source bean for JasperReports.
+ * Each field maps to a JRDesignField declared in the buildDesign() method.
+ * Field names must match exactly between this DTO's getter names and the
+ * JRDesignField names declared via ReportDesignHelper.addField().
+ */
+@Getter
+@Setter
+public class StaffReportDTO {
+
+    private String staffNumber;
+    private String fullName;
+    private String email;
+    private String departmentName;
+    private String positionName;
+    private String allocationStatus;
+    private String allocationPercentage;
+}
+```
+
+---
+
+## Key Design Decisions
+
+### Why Programmatic Design (JRDesign API)?
+
+1. **No XML files to maintain** — the report layout is Java code, versioned with the
+   application in the same repository. There are no `.jrxml` files to keep in sync.
+2. **Fully AI-agent-friendly** — coding agents write Java, not XML. The JRDesign API
+   produces the same result as `.jrxml` but is expressed as regular Java method calls.
+3. **Compile-time safety** — typos in field names, incorrect types, and missing elements
+   surface as Java compilation errors or obvious runtime exceptions in the `buildDesign()`
+   method, not as opaque Jasper XML parsing failures.
+4. **Dynamic layouts** — report structure can adapt based on parameters or data. For
+   example, columns can be conditionally included or excluded based on user selections
+   without maintaining multiple template variants.
+5. **No template/code synchronization** — the design and the data source DTO live in the
+   same codebase. When a DTO field is renamed, the `buildDesign()` method is updated in
+   the same commit. There is no separate XML file that can drift out of sync.
+
+### Why DTO as Data Source (not direct DB query)?
+
+1. **Separation of concerns**: Report definitions call module services, not repositories.
+   This preserves the module boundary enforced by Spring Modulith.
+2. **Testability**: Report data generation can be unit-tested by mocking the module service.
+3. **Flexibility**: The DTO can aggregate data from multiple sources (entities, computed
+   fields, cross-module lookups via public APIs) before feeding it to Jasper.
+4. **Type safety**: `JRBeanCollectionDataSource` reads Java getter methods, so field
+   mismatches between the DTO and `JRDesignField` declarations are caught early.
+5. **No SQL in reports**: Jasper reports contain only layout logic — no `<queryString>` SQL.
+   All data access goes through the standard service layer.
+
+### Report DTO Field Naming Convention
+
+- DTO field names use **camelCase** (Java standard)
+- `JRDesignField` names added via `ReportDesignHelper.addField()` must match the DTO
+  getter name exactly (e.g., field `staffNumber` maps to getter `getStaffNumber()`)
+- For nested objects, flatten them into the report DTO
+  (e.g., `staff.department.name` becomes `departmentName` in the DTO)
+
+---
+
+## Operational Notes
+
+- **Memory**: Large reports can consume significant memory during filling and export.
+  Consider streaming exports for very large data sets (JasperReports supports
+  `JRVirtualizer` for swapping pages to disk).
+- **Concurrency**: The `ReportService` is thread-safe. Compiled `JasperReport` objects are
+  cached in a `ConcurrentHashMap`. Each `generate()` call creates its own `JasperPrint`.
+- **Timeouts**: For long-running reports, consider executing generation asynchronously
+  via `@Async` or Spring Modulith events, with the result stored temporarily for download.
+- **Font embedding**: For PDF export, ensure fonts are embedded via the
+  `jasperreports-fonts` dependency. Configure `jasperreports.properties` or
+  `jasperreports_extension.properties` for custom font families if needed.
+- **Cache invalidation**: After deploying updated `buildDesign()` logic, call
+  `ReportService.evictReport(reportId)` to force recompilation from the new design.
+  In practice, a fresh deployment restarts the JVM and clears the in-memory cache
+  automatically. The `evictReport()` method is primarily useful during development
+  or in hot-reload scenarios.