fieldlens-desktop/PRINT_CAPTURE_ARCHITECTURE.md

FieldLens Print Capture Architecture

Target architecture

Linux

original document
  -> FieldLens Print CUPS queue
  -> FieldLens CUPS pre-filter
       -> /var/lib/fieldlens-print/capture
       -> FieldLens watcher / decode / sync
  -> normal CUPS rendering
  -> physical printer

The production Linux path does not depend on the RAW 9100 proxy. The CUPS pre-filter is authoritative for original-document capture.

The no-paper self-test uses the same CUPS pre-filter, then sends the rendered output to a local discard sink on 127.0.0.1:9101. Self-test success means the exact submitted document was observed by the FieldLens watcher, not merely accepted by CUPS.

Windows

Target:

original spool/document
  -> FieldLens native capture backend
       -> FieldLens capture / decode / sync
  -> normal Windows print pipeline
  -> physical printer

The current localhost:9100 RAW proxy remains a compatibility backend only until the native Windows backend is complete.

Windows native backend implementation track

1. Spike the supported Windows spool interception options:
   • custom port monitor,
   • print processor,
   • virtual printer / print support backend.
2. Prefer the least-privileged option that can capture the spool/document before final device rendering while returning the job to the normal Windows print pipeline.
3. Package and register the native component from the FieldLens installer with repair/remove support.
4. Preserve the existing FieldLens capture event contract so OCR/barcode, history, sync, and UI do not care which platform backend produced the job.
5. Support USB, WSD, locally installed, and network printers without requiring destination TCP/9100.
6. Add health checks that verify the native backend is installed, loadable, and attached to the FieldLens queue.
7. Add an end-to-end self-test that proves a submitted document creates a FieldLens capture event and reaches the downstream Windows print pipeline.
8. Remove the localhost:9100 compatibility backend after native backend rollout and migration are verified.

Health invariants

FieldLens must not report Ready unless the active platform capture backend is actually operational.

Linux Ready requires:

• FieldLens Print queue present, enabled, and accepting jobs;
• FieldLens Test Capture queue present, enabled, and accepting jobs;
• installed FieldLens CUPS filter present and Python-syntax-valid;
• production capture watcher running.

Linux self-test passes only when the exact submitted test document creates a matching cups-test capture event.

Windows Ready will eventually require the equivalent native-backend registration/load/queue checks, rather than only queue existence.