CSV_TO_PDF_REPORT/Envelope_Report_Generator_Requirements.md

ENVELOPE PRINTING REPORT GENERATOR - REQUIREMENTS FOUNDATION

1. Executive Summary

This application is a visual PDF report generator purpose-built for high-volume inkjet envelope printing operations. It eliminates production bottlenecks by empowering print operators to independently design envelope layouts, map CSV data fields, and generate print-ready PDFs without developer intervention. The system consists of two integrated components: a GUI template designer for visual layout creation and a high-performance CLI rendering engine capable of streaming multi-page PDFs from datasets containing up to 1,000,000 records in under 10 minutes.

• Primary Business Driver: Reduce job setup turnaround time and eliminate operator dependency.
• Target Users: Non-technical print shop floor operators.
• Technology Stack: Native Windows desktop application (C#/.NET or C++), Debenu Quick PDF Library 10.13, XML-based templates.

2. Product Vision

Vision Statement: Empower print operators with a self-service visual design tool that transforms CSV data into production-ready envelope PDFs in minutes, not hours, eliminating developer dependencies and reducing costly machine downtime.

• Success Metrics: Zero developer escalations for layout changes; setup time under 15 minutes; 100k envelopes rendered in under 10 minutes at 300 DPI.

3. Problem Statement

Current State: Inkjet machines require PDFs. Whenever a customer job specification changes (layout, font, images), operators must wait for developers to update scripts, causing production delays.

Future State: Operators use a drag-and-drop GUI to map CSV columns to layouts, preview live records, and generate PDFs via a CLI engine, requiring zero code changes.

4. Business Goals

1. Efficiency: Setup time reduced from 2-4 hours to <15 mins.
2. Resource Optimization: Eliminate developer bottlenecks for 90%+ of layout requests.
3. Throughput: Maximize hardware uptime.
4. Quality: Reduce errors through visual preview and automated overflow warnings.

5. User Types and Roles

Machine / Print Operator:

• Profile: Non-technical shop-floor staff.
• Responsibilities: Load CSVs, create/edit templates, map fields, preview records, generate PDFs.
• Access: Flat access model (all operators have full permissions).

6. Primary User Journeys

1. New Layout: Operator sets canvas size → loads CSV → drags fields/images onto canvas → aligns motifs → previews → generates PDF.
2. Layout Tweak: Operator loads existing XML template → adjusts font size or position → Saves → Renders.
3. High-Volume Run: Operator loads 1M record CSV → scans validation report for overflows/missing images → triggers background CLI render → monitors progress bar while continuing to design other jobs.

7. Functional Requirements

ID	Requirement	Description
FR-1	GUI Designer	Custom HxW dimensions (inches/mm/pts); Ruler/Margin guides; Snap-to-grid; Properties panel (X/Y, Font, Z-Order, Color).
FR-2	Toolset	Text boxes, Dynamic Field tokens, Rectangles, Lines, Static Images, Dynamic Image fields (path-based).
FR-3	CSV Mapping	Manual drag-and-drop mapping of column headers to tokens (e.g., {{Full Name}}).
FR-4	Design Aids	Multi-level Undo/Redo (session-based); Alignment/Distribution tools; Copy/Paste/Duplicate.
FR-5	Validation	Pre-render scan for text overflow, missing fonts (blocking), and missing image files (warning).
FR-6	Two-Tier Architecture	GUI shells out to a headless CLI engine for background rendering.

8. Business Rules

• Line Suppression: If a field like {{Address2}} is empty, the subsequent lines shift up to eliminate gaps.
• DPI Scaling: Automatic proportional scaling of elements when switching between 300 and 600 DPI.
• Z-Order: Numeric values where 0 is the bottom-most layer.
• Dynamic Images: Load image from file path specified in CSV; show placeholder if specific record path is broken.

9. Data and Integration Requirements

• Source: CSV with header row. No schema required.
• Paths: Support for local and UNC network paths (\\server\share\file.bmp).
• PDF Engine: Debenu Quick PDF Library 10.13 (64-bit DLL).
• Format: PDF 1.4+, RGB color space, uncompressed or Flate compression.

10. Security, Access, and Compliance Requirements

• Access: Windows login is sufficient; no app-level password needed.
• Audits: No audit logs required.
• Data Cleanup: Manual; no auto-purging of CSVs or PDFs.
• Confidentiality: Standard file system permissions; no extra encryption at rest.

11. Reporting and Operational Needs

• Completion Summary: Total records, total pages, elapsed time, and warning count.
• CLI Progress: Stdout stream providing progress in the following format:

PROGRESS|current|total|%|ETA|rate

• Notifications: In-app completion notification only.

12. Edge Cases and Failure Scenarios

Scenario	Behavior
Malformed CSV	Warn and list row errors.
Missing Images	Render page with placeholder; log warning; do not stop render.
Missing Font	Block render and show error.
Disk Full	Abort and delete partial file.

13. Non-Functional Requirements

• Performance: 100k records @ 300 DPI in <10 mins.
• Responsiveness: GUI must remain interactive during CLI background render.
• Output Size: Final PDF <2 GB (requires font subsetting/compression).
• Stability: Streaming architecture to maintain low memory footprint on 1M records.

14. Assumptions

• Operators have modern Windows 10/11 hardware.
• Barcode fonts are pre-installed on the OS.
• Debenu library license is available.
• Network latency for UNC paths is minimal (local LAN).

15. Risks

Risk	Description	Mitigation
File Size	1M page PDFs might exceed 2GB/OS limits	Phase 2 batching
Network Outage	UNC paths dropping during render	3x retry logic
Performance	Debenu library bottlenecks at extreme scale	Early stress testing

16. Dependencies

• DebenuPDFLibrary64DLL1013.dll
• .NET Framework / C++ Redistributable
• Windows Font Registry

17. In Scope for MVP

• GUI Designer (Drag-drop fields, shapes, images)
• Alignment/Distribution tools
• XML Template Save/Load
• CSV Data Grid + Preview Pane
• Line suppression logic
• CLI Engine (300 DPI, single PDF output)
• Async Progress Monitoring
• Support for 1M records

18. Out of Scope for MVP

• 600 DPI
• Page Rotation
• PDF Batching/Splitting
• Autosave/Crash Recovery
• Conditional Logic (If/Then branding)

19. Future Phases

• Phase 2: 600 DPI, Page Rotation, PDF Batching (Split by 2GB/Count)
• Future: Autosave, Template version history, SQL Database connectivity

20. Suggested Epics

1. Template Designer GUI Foundation
2. CSV Integration & Field Mapping
3. Live Preview & Record Navigation
4. CLI Rendering Engine (Debenu Integration)
5. Layout/Alignment Efficiency Tools
6. Dynamic/Network Image Handling

21. Suggested Features by Epic

Epic	Features
Epic 1	Canvas HxW, Ruler, Snap-to-grid, Properties Panel
Epic 2	CSV Picker, Column List dragging, {{Token}} parsing
Epic 3	Side-by-side view, Record jumper (1–1M)
Epic 4 (CLI)	Param handling (-t, -c, -o), Progress stdout, Exit codes

22. Sample User Stories

• As an operator, I want to drag ZipCode onto the envelope so it prints in the correct location.
• As an operator, I want to see a magenta box if an image is missing so I can fix the CSV path.
• As an operator, I want to align three text boxes to the left so the address looks professional.

23. Acceptance Criteria for Key Stories

US: Generate 100k PDF

• Given: Valid XML and 100k row CSV.
• When: “Generate PDF” is clicked.
• Then:
  • CLI spawns background process
  • GUI stays responsive
  • Progress updates every 1s
  • Finish in <10 mins
  • PDF <2GB

24. Open Questions

• Should templates keep absolute or relative paths for logos?
• Is there a specific timeout for slow network shares (UNC)?

25. Recommended Agile Delivery Approach

• Sprints: 1-week intervals.
• Slicing: Vertical (deliver end-to-end “Text only” render first, then add Images, then add Shapes).
• Definition of Done (DoD): Working code, self-tested with sample ballot CSVs.