CGW-Printing/IMPLEMENTATION_PLAN.md

Harbor/Clipper Print Service - Implementation Plan

TL;DR: Build a persistent Windows service that monitors for new print capture files, immediately moves them to prevent overwrites, queues them for ordered processing, and sends multi-tray print jobs to laser printers with document-type-specific configurations.

Recommended Approach: C#/.NET 8+ Windows Service with FileSystemWatcher, print queue, and configurable document templates. C# is completely free (.NET SDK), has superior Windows printer APIs, and excellent service infrastructure.

---

Steps

Phase 1: Service Foundation (Parallel work possible after step 1)

1. Create Windows Service project structure using .NET 8+ Worker Service template

   • Use BackgroundService base class for hosting
   • Configure as Windows Service with Microsoft.Extensions.Hosting.WindowsServices
   • Set up dependency injection, logging, and configuration (appsettings.json)

2. Implement file monitoring system (parallel with step 3)

   • FileSystemWatcher on Captures folder with Created, Changed, and Renamed events
   • Debounce logic to handle rapid file creation (buffer 100-200ms)
   • Immediate file move to processing queue folder with GUID-based naming to prevent collisions
   • Include original filename, timestamp, and metadata in queue

3. Design configuration system (parallel with step 2)

   • Document type definitions (invoice, order, delivery, etc.)
   • Per-document-type settings: printer name, tray sequence, content transformations
   • Global settings: queue folder paths, archive settings, retry policies
   • JSON schema for easy editing

Phase 2: Command Interface & Queue Management

4. Create CLI command handler (depends on 1)

   • Parse -f <filepath> -t <doctype> -o <ordernumber> arguments
   • Check if service is running via named pipe or TCP
   • If running: send command to service via IPC
   • If not running: log error or auto-start service
   • Return exit code immediately

5. Build print job queue (depends on 1)

   • Thread-safe queue with priority/ordering (FIFO by default, configurable)
   • Persistent queue state (survive service restart)
   • Job metadata: source file, document type, order number, timestamp, retry count
   • Status tracking: pending, processing, completed, failed

6. Implement IPC mechanism (depends on 4, 5)

   • Named pipe server listening for commands from CLI
   • Deserialize command → create job → enqueue
   • Return acknowledgment to caller

Phase 3: Printer Integration

7. Implement queue-based printer control (depends on 5)

   • Use System.Drawing.Printing.PrintDocument with Windows print queue
   • Multi-page document with dynamic PageSettings.PaperSource for tray selection
   • Per-printer tray mapping configuration (map logical tray numbers to physical PaperSource indexes)
   • Fallback handling when tray empty (configurable: fail job, use default tray, alert)
   • Optional: Print to PDF for testing/archiving

8. Build document processor with Graphics rendering (depends on 7)

   • Read queued capture file and parse text content
   • Apply document-type-specific transformations:
     • Line position adjustments using Graphics.DrawString() coordinates
     • Text removal/replacement via regex patterns
     • Font and formatting configuration per document type
     • Future: header/footer injection, graphics overlay, logo placement
   • Render each page with Graphics API for pixel-perfect control
   • Generate multi-page PrintDocument with correct tray sequence
   • Send to Windows print queue

9. Add printer routing logic (depends on 7, 8)

   • Map document types to printer(s) and tray sequences
   • Support multiple printer profiles per document type
   • Configuration: { "invoice": { "printer": "LaserJet-1", "trays": [3,4,1,2] } }

Phase 4: Reliability & Operations

10. Implement error handling & retry (depends on 5, 8)

    • Printer offline detection → requeue with exponential backoff
    • File read errors → log and move to error folder
    • Max retry limit → move to dead letter queue
    • Detailed logging with correlation IDs

11. Add file lifecycle management (depends on 2)

    • Post-processing: delete or move to archive folder (configurable per document type)
    • Archive folder structure: organized by date, document type, or both
    • Retention policy support (future: auto-cleanup old archives)

12. Create service installer & deployment (depends on all previous)

    • MSI installer or PowerShell install script
    • Service registration with sc.exe or WiX toolset
    • Auto-start configuration
    • Uninstall/upgrade support

Phase 5: Testing & Validation

13. System testing (depends on 12)

    • Test rapid file creation (simulate Harbor/Clipper speed)
    • Verify no overwrites or missing files
    • Confirm correct print order
    • Test printer offline scenarios
    • Validate tray sequences for each document type

14. Integration with Harbor/Clipper (depends on 13)

    • Replace current Rust CLI calls with new CLI
    • Monitor production for 24-48 hours
    • Compare output quality and reliability
    • Performance tuning if needed

---

Relevant Files

To be created:

• PrintService/Program.cs — Service host and startup configuration
• PrintService/Worker.cs — Background service implementing FileSystemWatcher and queue processor
• PrintService/Models/PrintJob.cs — Job data model
• PrintService/Models/DocumentConfig.cs — Document type configuration schema
• PrintService/Services/FileMonitorService.cs — File watching and immediate move logic
• PrintService/Services/PrintQueueService.cs — Queue management and processing
• PrintService/Services/PrinterService.cs — Queue-based printer control with tray commands
• PrintService/Services/DocumentProcessor.cs — Text parsing and Graphics rendering
• PrintService/Services/IpcService.cs — Named pipe listener for CLI commands
• PrintService/appsettings.json — Configuration file for document types, printers, paths
• PrintServiceCLI/Program.cs — Command-line tool for sending commands to service
• PrintService.sln — Solution file

Existing:

• Captures/ — Source folder for Harbor/Clipper output files (will be monitored)

---

Verification

1. Unit tests: Queue ordering, configuration parsing, tray sequence generation
2. Integration test: Create 50 files in 10 seconds → verify all printed in order with correct trays
3. Stress test: 1000+ files → no overwrites, no missing files, proper ordering
4. Manual test: Print each document type to each configured printer and verify tray usage
5. Production validation: Monitor service for 48 hours, compare output count with Harbor/Clipper expected count
6. Error scenario testing: Unplug printer mid-job → verify retry → reconnect → verify job completes

---

Decisions

Language: C#/.NET 8+

• Rationale: Free, best Windows service/printer APIs, excellent tooling, easier printer control than Rust
• Alternative: Could still use Rust with windows-rs crate, but printer control is more complex

Architecture: Service with IPC (Named Pipes)

• CLI tool sends commands → service processes asynchronously
• Decouples Harbor/Clipper from processing delays

File handling: Immediate move with GUID renaming

• Critical: Prevents timestamp collision overwrites
• Original metadata preserved in queue state

Queue persistence: JSON file or SQLite

• Survives service restart
• Allows inspection/recovery

Configuration: JSON file (appsettings.json)

• Editable without recompilation
• Per-document-type printer/tray/transformation settings

Printer control: PrintDocument with Windows print queue

• Per-page tray control via PageSettings.PaperSource
• Content rendered using Graphics.DrawString() for positioning control
• Jobs appear in Windows print queue (pausable, survives restarts)
• Can print to PDF for testing

Scope included:

• Windows service with file monitoring
• Command-line interface for Harbor/Clipper integration
• Multi-tray printer control via Windows print queue
• Configurable document routing
• Archive/delete options
• Error handling and retry logic
• Content transformation with Graphics rendering (line positioning, text removal)

Scope excluded (future enhancements):

• GUI management console (use config file + logs for now)
• Advanced document parsing/templating (start with regex transformations)
• Web API or remote monitoring
• Database storage (use file-based queue initially)
• Automatic printer discovery
• Print preview or validation UI

---

Further Considerations

1. Printer-specific tray mapping: Need to identify your laser printer models and test PaperSource indexes. Do you know the printer makes/models?
2. Content transformation complexity: You mentioned looping line items. For Phase 1, suggest simple regex-based transformations. If parsing becomes complex, consider a template engine (Scriban, Handlebars.NET) in Phase 2.
3. Testing environment: Do you have a test laser printer or can we print to PDF initially to verify tray selection and content rendering work correctly?

---

Benefits of Queue-Based Approach

• ✅ Visibility: Jobs appear in Windows print queue UI
• ✅ Resilience: Queue survives service restarts
• ✅ Control: Can pause/cancel jobs through Windows
• ✅ Testing: Print to PDF for verification without paper waste
• ✅ Content Control: Graphics.DrawString() gives pixel-perfect positioning for your line adjustments
• ✅ Debugging: Easier to troubleshoot than raw printer commands