# AOT Printer Agent — IDE Master Prompt Act as a senior systems architect, senior Go engineer, senior Windows service engineer, and senior enterprise integration engineer. Your task is to design, document, and start implementing a **production-oriented AOT Printer Agent** for thermal printing in branch environments. The required final deliverable is a **complete Markdown technical document** plus a **starter implementation plan and code scaffolding** that we can execute immediately. --- ## 1) Product Context We are building this for **AOT**, a Laravel cloud application. AOT cloud is responsible for: - creating print jobs - storing print queue state - storing audit logs - storing printer configuration and routing rules - assigning jobs to the correct target printer/device The local **AOT Printer Agent** is responsible for: - running permanently on a Windows machine inside the branch - auto-starting with Windows - registering itself with AOT cloud - sending heartbeat/status updates - syncing local printer information when needed - claiming print jobs from the cloud - executing thermal printing locally and silently - reporting print results back to the cloud - exposing local diagnostics if needed **Important architectural rule:** - The cloud must never connect directly to printers. - The cloud must never rely on browser tabs for printing. - The local agent must be the execution layer. - Printing must continue working even if no browser is open. --- ## 2) Strategic Direction This is not an MVP shortcut. We want the **long-term final direction**. Choose decisions that are stronger long-term, even if implementation is a bit heavier. ### Technology direction Use: - **Go** for the local agent - **Windows Service** as the runtime model - **Laravel cloud APIs** for registration, heartbeat, claim, and result reporting Avoid: - QZ Tray - browser-based printing - Electron - solutions that require the browser to stay open --- ## 3) Core Problem to Solve We need a robust local print agent that can print to thermal printers in branch environments. Supported scenarios: - LAN / IP thermal printers via raw TCP socket (commonly port 9100) - Windows-installed / USB thermal printers - ESC/POS printing The system must support: - silent printing - automatic execution - retries - local logging - printer diagnostics - cloud synchronization - future scalability --- ## 4) Print Result Requirements The design must explicitly support **two levels of print success**: 1. **Sent / Delivered** - The agent successfully connected to the printer and sent the print bytes. 2. **Confirmed** - The printer itself confirmed a printable/ready/printed state through supported feedback or status commands. - This may not be supported by every printer. The design must clearly explain: - when we can only mark a job as `sent` - when we can mark a job as `confirmed` - how unsupported printers should be handled - how this is stored and reported to AOT cloud --- ## 5) Cloud ↔ Agent Communication Rule The agent must always communicate **outbound** to the cloud. The cloud should not directly call the agent over inbound network connections. The communication model must be: - register device - authenticate device - heartbeat - printer sync - claim jobs - update job status - upload diagnostics We want a reliable enterprise-safe model that works behind NAT/firewalls. --- ## 6) What You Must Produce You must produce the output in **three major parts**: ### Part A — Architecture Decision Write a strong architecture decision that explains: - why Go is chosen over Node.js for the long-term agent - why Windows Service is chosen - why cloud-to-agent direct communication is rejected - why agent-outbound HTTPS claim model is chosen - why browser/QZ/Electron approaches are rejected for this direction - how printer execution should be separated from business routing logic ### Part B — Full Markdown Technical Spec Create a complete implementation-ready Markdown file named exactly: `AOT_PRINTER_AGENT_TECHNICAL_SPEC.md` The document must be structured, clear, and suitable as the official implementation reference. ### Part C — Starter Implementation Plan + Code Scaffolding Provide: - folder structure - package/module breakdown - starter files - skeleton code snippets - Windows service setup plan - testing plan - first implementation milestones --- ## 7) Required Markdown Structure The Markdown document must contain at least the following sections: # AOT Printer Agent Technical Spec ## Overview ## Goals ## Non-Goals ## Final Architecture Decision ## Runtime Model ## Windows Service Design ## Cloud Communication Model ## Device Registration and Authentication ## Heartbeat Model ## Printer Discovery and Registration ## Printer Types Supported ## Print Execution Pipeline ## Print Status Model ## Sent vs Confirmed Semantics ## LAN Printer Integration ## USB / Windows Printer Integration ## ESC/POS Payload Strategy ## Job Claim and Lease Model ## Retry and Failure Handling ## Local Persistence Strategy ## Diagnostics and Observability ## Security Model ## API Contract with Laravel Cloud ## Suggested Laravel Schema Adjustments ## Agent Project Structure ## Go Package Design ## Service Lifecycle ## Install / Update / Rollback Strategy ## Testing Strategy ## Local Development Plan ## Phase 1 Build Plan ## Phase 2 Hardening Plan ## Open Questions ## Recommended Decisions --- ## 8) Technical Decisions the Document Must Make Do not stay neutral. Choose and justify concrete decisions. The document must decide: - how device identity is generated and stored - how device token authentication works - where local config is stored - whether local persistence is JSON or SQLite - how printer records are stored locally vs in cloud - whether polling or long polling is used first - how lease/claim token works - how duplicate printing is prevented - how retries are triggered and capped - how printer capability flags are stored - how status-aware printers differ from send-only printers - how LAN printers are configured (IP + port + protocol) - how Windows-installed printers are referenced - how service logs are written and rotated - how the service behaves on reboot - how install/uninstall/update should work operationally --- ## 9) LAN / IP Printer Requirements You must explicitly design support for network printers. Cover: - storing `ip_address`, `port`, `protocol` - default raw TCP printing flow - ESC/POS payload transmission over socket - timeout strategy - test print flow - error handling - status query possibility if supported - how `sent` vs `confirmed` should work for network printers --- ## 10) USB / Windows Printer Requirements You must also explicitly design support for Windows-installed printers and USB-connected printers. Cover: - how the agent identifies the printer - how the printer is configured locally - adapter design - fallback behavior if direct USB/raw is not available - how to abstract both LAN and Windows printers behind one execution interface --- ## 11) Print Status Model You must define a serious print state model. At minimum consider: - pending - claimed - sending - sent - confirmed - failed - retryable - cancelled - expired You must decide: - which states live in cloud - which states are only local runtime events - what status payloads are sent back to cloud - how printer capability affects status confidence --- ## 12) Security Requirements The document must include: - device token authentication - secure local secret storage approach - API request signing or equivalent if needed - prevention of arbitrary local print abuse - ensuring the agent only prints jobs claimed from cloud - claim token validation - replay protection ideas --- ## 13) Local Agent Architecture Requirements The Go project must be broken into maintainable packages. At minimum include modules for: - bootstrap / entrypoint - Windows service lifecycle - config - local storage - cloud API client - device auth - heartbeat - printer discovery - printer adapters - ESC/POS builder or payload handling - job claim service - job executor - retry logic - diagnostics - logger --- ## 14) Code Scaffolding Requirements Provide starter scaffolding for at least: - `cmd/agent/main.go` - service bootstrap - config loader - cloud client - printer interface - network raw printer adapter - windows printer adapter placeholder - job claim loop - job executor - heartbeat loop - logger setup - installation PowerShell script The code does not need to be 100% complete, but it must be realistic and implementation-oriented. --- ## 15) Testing Requirements You must include a practical testing strategy: - local development environment - fake Laravel endpoints if needed - network printer test path - mock printer adapter strategy - test print scenario - retry scenario - offline scenario - duplicate prevention scenario - Windows service startup test Also define a **first test milestone** that proves the architecture works end to end. Example milestone: - manually create one print job in Laravel - agent claims it - agent sends a test ESC/POS payload to a configured network printer - agent reports `sent` - if printer feedback is supported, agent reports `confirmed` --- ## 16) Implementation Expectations After producing the Markdown document, continue by proposing the **first actual implementation steps** in order. That means: 1. create the repo/folder structure 2. create base Go project 3. create config and logging 4. create Windows service shell 5. create cloud API client 6. create heartbeat 7. create claim loop 8. create network printer adapter 9. create test print flow 10. define first integration test --- ## 17) Output Style Requirements - Be highly practical. - Prefer direct technical language. - Avoid generic theory. - Make concrete recommendations. - Use assumptions explicitly when needed. - Design for reliability, observability, and enterprise maintainability. - Assume branch devices are Windows machines. - Assume internal enterprise deployment. - Assume Laravel remains the cloud control plane. --- ## 18) Final Instruction Do not stop at high-level analysis. Produce: 1. the architecture decision 2. the full Markdown spec 3. the starter implementation plan 4. the starter code scaffolding 5. the first testing plan If there are multiple possible decisions, choose one as the **recommended final direction** and mention alternatives only briefly.