From 548ad9c8b20bcaa43f8b642d9c8d181b557bfec3 Mon Sep 17 00:00:00 2001 From: Kawa Date: Fri, 10 Apr 2026 10:36:02 +0200 Subject: [PATCH] docs: add domain research (stack, features, architecture, pitfalls, summary) --- .planning/research/SUMMARY.md | 139 ++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 .planning/research/SUMMARY.md diff --git a/.planning/research/SUMMARY.md b/.planning/research/SUMMARY.md new file mode 100644 index 0000000..355442d --- /dev/null +++ b/.planning/research/SUMMARY.md @@ -0,0 +1,139 @@ +# 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*