docs(designs): add First-Print pipeline design

[strausmann]

Summary

Adds the design document for the First-Print pipeline — the first end-to-end print path targeting the Brother PT-P750W.

This is a design-only PR, no code changes. Opening as a Draft to gather AI-assistant review (Copilot, Gemini Code Assist) on the design itself before any implementation work begins.

What this introduces

• PrinterBackend Protocol as the extension point for hardware adapters (siblings to ADR 0004's PrinterModel plugin pattern)
• PTouchBackend as the first concrete adapter, wrapping the ptouch library
• PTP750WDriver (PrinterModel) + PTP750WPrinter (bridge to PrintQueue's _PrinterLike)
• PrintService orchestrator (lookup → render → enqueue)
• POST /print (async, returns job_id) + GET /jobs/{job_id} REST surface
• Pre-print validation chain with a tight PrinterError hierarchy and HTTP status mapping
• Testing strategy: pure unit + mock-backend integration + manual hardware smoke against a real PT-P750W
• Explicit Acceptance Criteria (11 items)

Open questions called out in the design

• ptouch status-block field surface — verify loaded_tape_mm availability in implementation Phase 1, otherwise fall back to raw parsing per Brother Raster Command Reference
• Mock backend location: keep under tests/ (pure test double) or move to app/printer_backends/mock_backend.py to enable local dev without hardware
• 5-minute in-memory job TTL is fine for First-Print; revisit alongside persistence work in Phase 5

Review focus areas

I'd appreciate feedback especially on:

1. Protocol shape — is the print_image + send_bytes + query_status split right, or should send_bytes wait until a concrete need (template editor) materialises? (YAGNI vs future-proofing)
2. Exception → HTTP mapping — does the 409 / 503 / 500 split make sense for the various hardware/state errors?
3. Backend instantiation in lifespan — local import of the mock for printer_backend=mock keeps test deps out of production, but feels slightly awkward. Better idiom?
4. Test-pyramid balance — sufficient coverage from pure unit + mock-integration, or should we add anything?

Next steps after this PR

1. Address review comments (Copilot, Gemini, maintainer)
2. Mark ready for review → merge as docs-only
3. Open feat/first-print implementation branch following the design here, with its own writing-plans implementation plan

Refs #22

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a comprehensive design document for the First-Print pipeline, aimed at enabling end-to-end printing functionality for the Brother PT-P750W. It defines the necessary architectural components, data flow, and error handling strategies required to integrate hardware adapters into the existing system, while also outlining clear acceptance criteria and testing methodologies to guide future implementation.

Highlights

• Architecture Design: Introduces the First-Print pipeline design, establishing a PrinterBackend protocol for hardware abstraction and a PTouchBackend adapter for the Brother PT-P750W.
• API and Orchestration: Defines the REST surface (POST /print, GET /jobs/{job_id}) and the PrintService orchestrator for handling template resolution, rendering, and queue management.
• Error Handling and Testing: Establishes a robust PrinterError hierarchy with HTTP status mapping and outlines a comprehensive testing strategy including unit, integration, and manual hardware smoke tests.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds a design document for the First-Print Pipeline, which establishes the architecture for printing to Brother PT-P750W devices via a REST API. The review feedback points out several necessary adjustments to align the design with the existing codebase and style guides. Key issues include the incorrect placement of model-specific code, protocol field naming mismatches, and the potential for synchronous I/O violations in asynchronous functions. Furthermore, the feedback identifies discrepancies in the usage of the TapeRegistry and PrintQueue components and advises against importing test-specific code into the application's lifespan logic.

[gemini-code-assist]

The design places PTP750WPrinter in app/services/printers.py, which violates Rule 17 of the Repository Style Guide (model-specific code must reside within app/printer_models/<series>.py). Additionally, the proposed printer_id field (line 137) should be named id to conform to the _PrinterLike protocol defined in backend/app/services/print_queue.py.

Suggested change

	| `PTP750WPrinter` | `app/services/printers.py` | Bridge: PrinterModel + Backend → PrintQueue's `_PrinterLike` |
	| `PTP750WPrinter` | `app/printer_models/pt.py` | Bridge: PrinterModel + Backend → PrintQueue's `_PrinterLike` |

References

1. Model-specific code outside app/printer_models/.py is a bug. ^(link)

[strausmann]

Fixed in 6c55a84. Moved PTP750WPrinter into app/printer_models/pt.py per ADR 0004, and renamed the attribute to id: str to match the _PrinterLike Protocol in backend/app/services/print_queue.py. Thanks for catching both.

[gemini-code-assist]

The description for send_bytes suggests opening a raw TCP connection. If this uses standard synchronous socket operations within an async def function (as defined on line 105), it would violate Rule 33 of the Repository Style Guide. Ensure asyncio.open_connection or asyncio.to_thread is used for the implementation.

References

1. Synchronous I/O in async functions is flagged. ^(link)

[strausmann]

Fixed in 6c55a84. The design now explicitly says send_bytes uses asyncio.open_connection to keep the call non-blocking. The ptouch library is synchronous, so its calls go through asyncio.to_thread; only the direct-TCP escape hatch needs open_connection.

[gemini-code-assist]

The call to self._tape_registry.for_pt_series(tape_mm) does not match the TapeRegistry implementation in backend/app/services/tape_registry.py, which uses lookup_pt(width_mm, media_type). Additionally, lookup_pt requires a media_type which is not provided here.

Suggested change

	tape_spec = self._tape_registry.for_pt_series(tape_mm)
	tape_spec = self._tape_registry.lookup_pt(tape_mm, options.get("media_type", MediaType.LAMINATED))

[strausmann]

Fixed in 6c55a84. The bridge now calls TapeRegistry.lookup_pt(tape_mm, media_type) with the real signature. media_type comes from a per-print options["media_type"] override, falling back to a constructor-injected default_media_type (typically MediaType.LAMINATED for the dominant TZe-Tape case). Pre-print status validation catches a mismatched physical tape via TapeMismatchError.

[gemini-code-assist]

The instantiation of PrintQueue does not match the existing implementation in backend/app/services/print_queue.py. The current __init__ expects a list of printers (printers: list[_PrinterLike]) and does not accept a max_concurrency argument.

Suggested change

	queue = PrintQueue(printer=printer, max_concurrency=settings.printer_max_concurrency)
	queue = PrintQueue(printers=[printer])

[strausmann]

Fixed in 6c55a84. PrintQueue is now instantiated as PrintQueue(printers=[printer]) and the bogus printer_max_concurrency setting is removed. The queue gives each printer its own dedicated worker by design, so there is no concurrency knob — added an explanatory note in the Settings section.

[gemini-code-assist]

Importing from tests/ in production code (app/main.py) is a maintainability anti-pattern. As noted in the 'Open question' on line 258, the mock backend should be moved to app/printer_backends/ if it is intended to be used for local development or within the application lifespan.

Suggested change

	from tests._fakes.mock_backend import MockPrinterBackend
	from app.printer_backends.mock_backend import MockPrinterBackend

[strausmann]

Fixed in 6c55a84. The mock backend moves from tests/_fakes/mock_backend.py to app/printer_backends/mock_backend.py. That removes the cross-boundary import and keeps the mock available for local dev (PRINTER_HUB_PRINTER_BACKEND=mock). The earlier "open question" about its location is now resolved in the Lifespan section.

[Copilot]

Pull request overview

Adds a draft design document describing the planned “First-Print” end-to-end pipeline (REST → template/lookup → render → PrintQueue → PT-P750W) for the backend, including proposed abstractions (PrinterBackend, PrintService), REST surface, error mapping, and a test strategy/acceptance criteria.

Changes:

• Introduces a detailed architecture proposal for a first working print path targeting the Brother PT-P750W.
• Specifies proposed backend protocol(s), service orchestration flow, REST schemas, and exception→HTTP mapping.
• Outlines testing layers (unit/integration/manual hardware smoke) and acceptance criteria for the phase.

Comments suppressed due to low confidence (1)

docs/designs/2026-05-15-first-print.md:225

• PrintJobStatusResponse doesn’t line up with the existing in-memory Job model: the queue uses state values like printing/completed (not running/done), and timestamps are submitted_at/started_at/finished_at (not created_at). If the REST surface is meant to be a thin view over PrintQueue.Job, consider aligning these names/values (or explicitly documenting the translation).

class PrintJobResponse(BaseModel):
    job_id: str
    status: Literal["queued"]

class PrintJobStatusResponse(BaseModel):
    job_id: str
    status: Literal["queued", "running", "done", "failed"]
    error_code: str | None = None
    error_message: str | None = None
    error_detail: dict[str, Any] | None = None
    created_at: datetime
    started_at: datetime | None = None
    finished_at: datetime | None = None

</details>

[strausmann]

Fixed in ae96393. The data flow and lifespan example now use PrintQueue.submit(printer_id, image, tape_mm, **options) → job_id with the real signature. The single printer.id is stored on app.state.printer_id and passed by PrintService; multi-printer routing comes with the persistence work.

[strausmann]

Fixed in ae96393. The spec now uses the actual JobState enum values (queued / paused / printing / completed / failed / cancelled) everywhere — data flow, REST schema, integration tests, and acceptance criteria. The PrintJobStatusResponse.status is typed as JobState directly.

[strausmann]

Fixed in ae96393. The Persistence subsection now correctly states that _jobs has no eviction today and matches the existing TODO. Bounded job store + TTL/LRU is moved to Phase 5 alongside SQLite. The practical impact for First-Print is documented (small payloads, low daily volume, process restart acts as coarse eviction).

[strausmann]

Fixed in ae96393. options: PrintOptions = Field(default_factory=PrintOptions) so each request gets its own instance. Added model_config = ConfigDict(frozen=True) on PrintOptions as belt-and-braces against mutation across requests.

[strausmann]

Fixed in ae96393. Introduced a dedicated RawLabelData Pydantic model that mirrors LabelData's shape (title, primary_id, qr_payload, secondary as list — coerced to tuple in LabelData). PrintService constructs LabelData(**raw.model_dump(), source_app="manual") — the client cannot set source_app (it is always "manual" for the raw path).

[strausmann]

Fixed in ae96393. The spec now states explicitly that build_print_job delegates to the ptouch library's internal raster builder (exact entry point confirmed in plan Phase 1; fallback to a raw encoder per Brother Raster Command Reference if not exposed). query_status raises ValueError when a non-matching, non-empty host argument is passed, rather than silently ignoring it. The driver now genuinely fulfills the Protocol contract.

[strausmann]

Fixed in ae96393. send_bytes now specifies the full lifecycle: writer.write(raster) → await writer.drain() → writer.close() → await writer.wait_closed(). The spec calls both drain and wait_closed mandatory to avoid truncated raster under backpressure.

[strausmann]

Fixed in ae96393. Existing settings (pt750w_host, pt750w_port, ql820_host, ql820_port) stay as-is — no rename, no migration. First-Print adds only three new fields: printer_backend, printer_model, printer_queue_timeout_s. Each backend's from_settings(settings) knows which existing per-model host field to read (PTouchBackend reads pt750w_*, future BrotherQLBackend reads ql820_*). A migration to a more general structure is deferred until multi-printer support actually arrives.

[strausmann]

Update — extensibility baked in (7fb6bf3)

Following the discussion about adding new printers / customising existing ones, I extended the design so that plugin discovery is a day-one property rather than a phase-2 retrofit. Five concrete extension paths are now documented (decorator backend, subclass driver, new series, third-party pip package, and same-series add-on).

Concrete architecture changes in this commit:

• ModelRegistry is driven by setuptools entry_points (group label_hub.printer_models); built-in PT-Series self-registers.
• New BackendRegistry mirrors that for backends (group label_hub.printer_backends); ptouch and mock self-register.
• Backends expose from_settings(settings) → PrinterBackend so the lifespan has no per-backend if-tree.
• Bridge to PrintQueue's _PrinterLike becomes Driver.make_queue_printer(...) — a method on the driver, not a separate exported class. Subclassed drivers inherit it for free.
• Settings: printer_model (series-agnostic) replaces the PT-only printer_pt_model; both printer_backend and printer_model are plain strings so third-party plugins can be selected without code change.

Lifecycle hooks (before_print / after_print) deliberately stay out of scope for First-Print — the documented paths 2 and 3 cover every realistic case today and the PrinterModel Protocol stays unchanged.

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the design for the 'First-Print' pipeline, establishing the end-to-end flow from a REST API to physical printing on Brother PT-P750W hardware. The design covers a new PrinterBackend protocol, a PTouchBackend implementation, and the orchestration logic within a PrintService. The reviewer provided several critical architectural insights: specifically, the send_bytes method should be removed to adhere to the YAGNI principle, and raw TCP connections should be avoided to prevent resource conflicts with the ptouch library. Additionally, the reviewer noted that the PTP750WDriver implementation currently violates the PrinterModel protocol by ignoring the host argument in query_status and raising NotImplementedError for build_print_job, necessitating a refactor of the protocol or the driver to ensure type safety and runtime stability.

[gemini-code-assist]

Regarding the send_bytes open question: following the YAGNI principle (cited in line 410 for lifecycle hooks), it is recommended to omit this from the initial PrinterBackend protocol. It introduces redundant connection logic and increases the maintenance surface before a concrete use case exists.

References

1. Adhere to the YAGNI principle for features without immediate use cases, as applied to lifecycle hooks in the repository style guide. ^(link)

[strausmann]

Accepted. send_bytes removed from the PrinterBackend Protocol in 78cdab2 — YAGNI cut. No concrete caller in First-Print, and the second TCP path would conflict with ptouch's single session (your finding B). The escape hatch can be added back additively if a real use case appears (template editor writing raw raster, or a non-library backend); doing so is non-breaking.

[gemini-code-assist]

Opening a raw TCP connection to port 9100 while the ptouch library is active may cause 'Resource Busy' errors. Brother PT hardware typically supports only one active TCP session at a time. It is safer to route all traffic through the library's transport mechanism to ensure serial access.

References

1. Ensure compliance with Brother hardware limitations; the PT-series typically supports only one concurrent TCP connection per the Raster Command Reference. ^(link)

[strausmann]

Resolved by removing send_bytes (your finding A). A note about Brother PT-Series allowing only one concurrent TCP session is now part of the YAGNI rationale so future implementers don't reintroduce the second connection by accident.

[gemini-code-assist]

There is a conceptual mismatch between the PrinterModel protocol and the proposed PTP750WDriver. The protocol's query_status (line 32 of app/printer_models/base.py) is stateless, taking a host argument. However, the driver is stateful, being initialized with a backend that already contains the host. This results in an ignored host argument. Consider updating the PrinterModel protocol to reflect a stateful design if drivers are now expected to be bound to backends at instantiation.

References

1. Ensure alignment between protocol definitions and concrete implementations to avoid 'dead' arguments and maintain type safety.

[strausmann]

Valid alternative — and arguably the cleaner one. Kept the host-mismatch raise for First-Print so we don't touch the Protocol (which other PrinterModel call sites depend on), and documented the stateless-to-stateful Protocol refactor as a candidate follow-up PR in Open Questions. Bundling the Protocol change with First-Print would significantly expand scope; happy to file the follow-up issue once First-Print lands.

[gemini-code-assist]

Raising NotImplementedError for build_print_job violates the PrinterModel protocol (line 43 of app/printer_models/base.py). This will cause runtime failures in components expecting a full driver implementation. Refactor the protocol to make rasterization optional or move it to a sub-protocol (e.g., RasterizablePrinterModel) if the PT-series delegates this entirely to the backend.

References

1. A class claiming to implement a Protocol must fulfill all required methods to prevent runtime crashes.

[strausmann]

Valid alternative. Two viable resolutions: (a) delegate build_print_job to ptouch's internal encoder (kept in 78cdab2), or (b) refactor the Protocol so rasterization moves into a RasterizablePrinterModel sub-protocol. The decision depends on what ptouch actually exposes — confirmed in implementation plan Phase 1. Both options are now documented in Open Questions; whichever turns out to be needed is a non-disruptive change.