ImpTune/.planning/research/SUMMARY.md

Project Research Summary

Project: ImpTune Domain: IT admin tooling — printer deployment package generator Researched: 2026-04-10 Confidence: HIGH (with targeted MEDIUM on .intunewin format compliance)

Executive Summary

ImpTune is a self-hosted, single-container web application that automates the creation of printer deployment packages for IT admins and MSPs. The core workflow is: upload a printer driver ZIP, configure printer parameters (name, IP, print settings), and export either a .intunewin package (Intune Win32 app) or a plain ZIP (NinjaRMM script-based deployment).

The recommended stack is Python 3.12 + FastAPI 0.115.x + Jinja2 + HTMX + SQLite — no Node.js build pipeline, no SPA framework, no external database. The entire application ships as a single python:3.12-slim-bookworm container with a named volume for driver files and the SQLite database.

The most important architectural decision is .intunewin generation. IntuneWinAppUtil.exe is a Windows PE binary that cannot run in a Linux container. The format is fully documented through reverse engineering (svrooij.io, SvRooij.ContentPrep NuGet library) and must be reimplemented in Python using zipfile, pycryptodome (AES-256-CBC + HMAC-SHA256), and xml.etree.ElementTree. The top risks are concentrated in generated PowerShell scripts and driver management — scripts must handle Intune's 32-bit WOW64 execution context, correctly distinguish SYSTEM from elevated-admin identity, and use the mandatory two-step pnputil + Add-PrinterDriver sequence.

Key Findings

Recommended Stack

Python 3.12 + FastAPI for the backend, Jinja2 + HTMX for server-rendered UI with no build step, SQLite for lightweight persistence, and pycryptodome for .intunewin encryption. Single Docker container on python:3.12-slim-bookworm (never Alpine — breaks C-extension wheels).

Core technologies:

• FastAPI 0.115.x + Uvicorn 0.30.x: HTTP framework + file upload handling + StreamingResponse — async-capable, minimal boilerplate
• Jinja2 3.1.x + HTMX 2.0.x + Alpine.js 3.x: Server-side rendering, zero build step, ideal for internal CRUD tools
• SQLite (stdlib) + peewee 3.17.x: Zero-config single-writer persistence, no external DB needed
• pycryptodome 3.20.x: AES-256-CBC + HMAC-SHA256 for .intunewin encryption layer
• Tailwind CSS v4 CDN: Styling without a Node.js dependency

Expected Features

Must have (table stakes):

• Driver ZIP upload with INF parsing and DriverDesc dropdown (not free-text input)
• Printer config form: name, IP, port name, duplex, color/BW, paper size, default tray
• PowerShell install + uninstall + detection script generation
• SYSTEM detection, 64-bit WOW64 guard, pnputil two-step, idempotency in generated scripts
• .intunewin export (Python-native AES-256 encrypted ZIP-in-ZIP with detection.xml)
• NinjaRMM ZIP export (script + driver folder)
• Client/tenant label per printer

Should have (v1.x):

• Custom icon upload for Intune app display
• Driver file optimization hints
• One-click package regeneration
• Intune command preview panel

Defer (v2+):

• Direct Intune/NinjaRMM API push (requires OAuth, multi-tenant app registration)
• Real-time chat/notifications
• Mobile app

Architecture Approach

Layered single-process: thin API handlers → service classes → generator modules. Package generation is synchronous on the request thread (under 10s for typical driver bundles). Content-addressed driver storage (SHA256 keys) on a Docker volume. PS scripts always from Jinja2 templates, never string concatenation.

Major components:

1. API Layer (FastAPI routes) — HTTP endpoints for uploads, config CRUD, package export
2. Service Layer (domain logic) — INF parsing, printer config validation, client organization
3. Generator Layer (format-specific builders) — PS script templating, ZIP builder, .intunewin builder
4. Storage Layer (SQLite + volume) — driver file persistence, printer/client metadata

Critical Pitfalls

1. IntuneWinAppUtil.exe cannot run in Linux Docker — reimplement .intunewin format natively in Python; validate against real Intune upload early
2. pnputil two-step is mandatory — Add-PrinterDriver fails 100% on clean endpoints without pnputil /add-driver staging first; embed in script template unconditionally
3. Intune launches scripts in 32-bit PowerShell — WOW64 silently redirects System32/registry; every script needs PROCESSOR_ARCHITEW6432 relaunch guard
4. SYSTEM vs elevated-admin confusion — IsInRole(Administrator) returns true for both; check WindowsIdentity.Name -eq "NT AUTHORITY\SYSTEM" explicitly
5. Driver name mismatch — parse DriverDesc from INF at upload time, never trust user text; free-text driver names cause near-100% failure on clean endpoints

Implications for Roadmap

Phase 1: Foundation & .intunewin Validation

Rationale: The .intunewin Python reimplementation is the highest-risk technical decision — validate it first before building everything on top Delivers: Docker scaffold, SQLite schema, data models, .intunewin format spike tested against real Intune Avoids: Building export features on an unvalidated format assumption

Phase 2: Driver Management

Rationale: Everything downstream depends on having drivers uploaded and INF-parsed correctly Delivers: Upload, INF parsing (DriverDesc extraction), SHA256-keyed volume storage, unsigned driver warning Avoids: Free-text driver name pitfall by enforcing INF-derived names from day one

Phase 3: Printer Config & Script Generation

Rationale: Core deliverable — the PS install script with all correctness requirements baked in Delivers: Printer CRUD form, Jinja2 PS template with 64-bit guard, SYSTEM detection, pnputil two-step, idempotency, injection prevention Avoids: WOW64/SYSTEM/elevation pitfalls by building them into the template from the start

Phase 4: Package Export (NinjaRMM + Intune)

Rationale: NinjaRMM ZIP is simpler — validates script orchestration before tackling .intunewin complexity Delivers: NinjaRMM ZIP builder, then Intune .intunewin builder reusing Phase 1 validation; StreamingResponse download with cleanup Uses: zipfile (stdlib), pycryptodome, Phase 1 .intunewin builder

Phase 5: Web UI & Client Organization

Rationale: Build UI over validated API routes — all backend functionality is testable before UI work begins Delivers: HTMX + Jinja2 UI, driver library browser, client/tenant organization, Intune command preview Implements: Full HTMX interactive UI layer over existing FastAPI endpoints

Phase 6: Polish & v1.x Enhancements

Rationale: Defer until real MSP usage validates demand Delivers: Icon upload, driver size hints, one-click regeneration, UX refinements

Phase Ordering Rationale

• .intunewin validation first because it's the riskiest unknown — if the format can't be reimplemented, the Intune export strategy changes entirely
• Driver management before printer config because the printer form's driver dropdown depends on parsed INF data
• Script generation before export because both export formats wrap the same generated script
• NinjaRMM export before Intune because it's simpler and validates the packaging pipeline
• UI last because all API routes should be stable and testable before wiring up the frontend

Research Flags

Phases likely needing deeper research during planning:

• Phase 1: .intunewin format — MEDIUM confidence; must spike against real Intune upload
• Phase 3: PS script correctness — WOW64/SYSTEM/pnputil interaction effects require testing against a real Intune-managed device

Phases with standard patterns (skip research-phase):

• Phase 2: Driver upload + INF parsing — standard file upload + regex text parsing
• Phase 4: ZIP builder — Python zipfile stdlib, well-documented
• Phase 5: HTMX + FastAPI UI — well-documented pattern

Confidence Assessment

Area	Confidence	Notes
Stack	HIGH	Verified against official docs + 2025-2026 community consensus; no version conflicts
Features	HIGH	Verified against Microsoft Intune docs, MSP community guides, reference implementations
Architecture	HIGH	Layered single-container pattern well-established; IntuneWin builder internals MEDIUM
Pitfalls	HIGH	All critical pitfalls confirmed via official Microsoft docs + high-reputation community sources

Overall confidence: HIGH

Gaps to Address

• .intunewin byte-level format compliance: Validate Python-generated packages against a real Intune tenant in Phase 1 spike
• Multi-model INF parsing: HP/Ricoh drivers may have multiple DriverDesc entries per INF — validate in Phase 2
• pnputil + $PSScriptRoot under SYSTEM context: Validate path resolution behavior in Phase 3 testing
• ARM64 driver variants: Determine if ImpTune needs to handle ARM64 for Surface/Copilot+ devices

---

Research completed: 2026-04-10 Ready for roadmap: yes