diff --git a/PRINT_CAPTURE_ARCHITECTURE.md b/PRINT_CAPTURE_ARCHITECTURE.md new file mode 100644 index 0000000..6cfa7cd --- /dev/null +++ b/PRINT_CAPTURE_ARCHITECTURE.md @@ -0,0 +1,61 @@ +# FieldLens Print Capture Architecture + +## Target architecture + +### Linux + +```text +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: + +```text +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.