# Architecture and implementation plan

Samsara is a Windows Server and enterprise Linux retirement assessment tool. Desktop OS and assessed OS are independent.

## Project structure

- `samsara/ui`: Qt interface and background collection worker.
- `samsara/core`: hostname validation, OS detection and profile matching.
- `samsara/collectors`: offline fixtures, schema-validated JSON intake and local Linux collector.
- `samsara/analyzers`: evidence classification and transparent heuristic scoring.
- `samsara/reporting`: local HTML/JSON export.
- `samsara/models`: reserved for typed collection models.
- `samsara/assets`: labeled synthetic fixtures.
- `schemas`: versioned collection JSON contract.
- `powershell`: Windows PowerShell 5.1 local inventory modules, shared safe-error helpers and JSON driver.
- `tests`: core, parsing, detection, worker, UI and export tests.

## Implemented

The simplified UI starts on Analyze with This computer and Auto-detect selected. History, Reports and Settings are secondary pages. No fabricated assessment is inserted at startup. Local collection detects the OS and uses the Linux backend where available. Version mismatches and unsupported Windows collection fail explicitly. Saved inventories and synthetic samples have separate source choices. A dedicated Summary destination opens after collection, with retirement risk, OS/version, important software and scheduled work; comprehensive Networking, Software, Tasks, Dependencies and other tabs expose evidence. Reports can be saved immediately after an assessment; session history reopens previous results.

Linux collection provides read-only OS, service, timer calendar, system cron, TCP, package and mount observations. Missing evidence is represented by check status, never by synthetic substitution. Commands have cancellation, time/output limits and cleanup. See README for exact omissions.

## Remaining phases

1. Validate the implemented local Windows inventory on authorized Server hosts (2016/2019/2022/2025) before marking the milestone complete. Synthetic Windows contracts pass; native execution remains pending. Optional AD enrichment must not become a prerequisite.
2. Authorized Windows execution-host remoting and Linux SSH transport, explicit targets/authentication, host verification, bounded output, timeouts and cancellation. No infrastructure configuration.
3. Expand Linux inventory for user schedulers and remaining cron/anacron coverage, identities, share exports, disk usage and application-specific public certificates with least-privilege access.
4. Validate OS-specific application/critical infrastructure rules, observed versus inferred relationships and historical/manual verification workflows. No automatic retirement approval.
5. Production schemas, redaction, Windows/RHEL platform testing, packaging and signed releases.

The original empty repository had no existing application or project instructions. All current collection is local or offline; no enterprise targets are contacted in development.

## Windows local collection milestone

Added independent read-only PowerShell modules and the local Python backend, without replacing the existing application. OS identity is accepted only for known Server build/product-type combinations. The existing QThread routes Windows auto-detect/profile choices to the backend and retains the same result, history and reporting flow. Python runs each fixed local section in a separate supervised PowerShell process, with cancellation, per-section/overall budgets, output bounds and cleanup. Per-check UTC timestamps, sanitized errors, scope and permission limitations extend schema v1 additively; old fixtures remain valid. The real-host validation tool produces full private evidence and a separate metadata-only summary for review. Remote Windows collection is not part of this milestone.