# 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.