How does Pick Your Linux choose a distro?

It filters the distro dataset using the answers you provide and explicit modeled attributes such as installer experience, release model, package manager, hardware needs, and maintenance style. The result explains the relevant constraints and trade-offs.

Does it use hidden scores or opaque recommendations?

No. The project is designed around inspectable decision rules and schema-defined data. You can review the modeled fields, validation checks, and source code before relying on a result.

Can I browse the distro data without taking the flow?

Yes. The All distros and metrics page exposes the current dataset and lets you filter distributions by attributes such as release model, intended use case, and documentation ecosystem.

How current is the distro information?

Each distro record includes a last verified date. The fields are maintained snapshots, so use the linked official project site and documentation for release-specific details that may have changed.

How It Works

This page is a docs-driven overview of the decision engine, data model, and explainability rules behind Pick Your Linux.

Documentation Sources Covered

ARCHITECTURE.md
DATA_CONTRACT.md
DATA_RULES.md
QUESTION_CATALOG.md
CONSTRAINT_MAPPING.md
RESULTS_COPY.md
TESTING.md
TONE_AND_COPY.md
FRONTEND-IMPLEMENTATION-RULES.md

1. Product Promise

Pick Your Linux is a deterministic compatibility engine. It does not rank, score, or suggest a single best distro. It only filters with explicit rules and shows transparent reasons.

Multiple matches are expected when multiple distros satisfy the same constraints.
No hidden weights, popularity scores, or subjective recommendations are used.
You can change answers and immediately see how outcomes change.

2. Core Architecture

The system is split into strict layers to keep logic testable and UI dumb.

Data layer (`/src/data`): schemas, question catalog, distro dataset.
Logic layer (`/src/engine/logic.ts`): pure condition and patch evaluation.
State layer (`/src/engine/state.ts`): flow orchestration, progress, undo, results view models.
UI layer (`/src/components`): render-only components that consume view models.
Import direction is one-way: UI -> state -> logic.

3. Data Contract (UserIntent)

Every answer updates a single validated `UserIntent` object. This is the decision state.

Installation and maintenance preferences define setup and post-install friction tolerance.
Proprietary preference controls acceptance of closed-source components.
Hardware context includes architecture, RAM, secure boot, and GPU details.
Use-case tags include Gaming, Privacy, Work, Server, and OldHardware.
Optional refinement fields include desktop preference, release model, init system, and package manager.

4. Question Engine

Questions are data-driven. Each option contains deterministic JSON patches. Visibility is controlled only by explicit conditions.

Allowed patch ops: `set`, `add_tag`, `remove_tag`.
Allowed condition ops: `eq`, `neq`, `in`, `contains`, `and`, `or`.
No functions in data, no callbacks, and no runtime eval.
Question order and phase behavior come from the catalog, not UI logic.

5. Phased Journey

Flow depth is progressive and forward-only: Quick (Beginner) -> Intermediate -> Advanced.

Quick gathers high-signal constraints with minimal time.
Intermediate adds practical refinements (desktop style, update model, hardware clarifiers).
Advanced adds explicit system preferences (init, package manager, stricter controls).
Users can stop at results after quick/intermediate and continue refining later without restart.

6. Hard Constraints (Pass/Fail)

Hard constraints exclude incompatible distros. If a distro fails one hard rule, it is out.

GUI installer requirement excludes manual-installer distros.
No-terminal maintenance requirement excludes hands-on maintenance distros.
Avoid proprietary excludes distros requiring proprietary support.
Require proprietary excludes distros with no proprietary support.
Old hardware requirement excludes distros not suitable for low-end or older hardware.
Secure boot and NVIDIA preferences apply additional explicit compatibility checks.

7. Soft Compatibility Reasons

Soft reasons do not rank distros. They only explain why a compatible distro may fit better for specific goals.

Gaming and privacy posture generate explainability reasons.
Desktop/release/init/package-manager preferences add explicit match reasons.
Choice-driven reasons and strict-filter matches are shown separately in results.

8. Results and Explainability

Results are presented as compatibility outcomes, not recommendations.

Each card includes strict filters matched, choice-driven reasons, and potential friction.
Explainability panel shows active constraints and excluded distro reasons.
Compare page exposes distro attributes side-by-side using the same source data.
Sorting defaults to most matches first; user filters are explicit and reversible.

9. Data Quality and Audits

Distro data follows schema validation plus consistency audits.

Schema validation enforces legal values for every distro attribute.
Audit rules flag suspect combinations (for example NVIDIA support vs proprietary policy).
Secure boot claims and rolling-maintenance expectations are audited for defensibility.

10. Testing and Validation Gates

Changes are expected to pass deterministic validation pipelines.

Flow validator checks that question visibility and transitions are coherent.
Question and distro validators enforce schema and catalog integrity.
Engine tests cover condition logic, patch behavior, completion, and undo.
The goal is explainable and reproducible behavior under strict typing and schema control.

11. UX and Copy Rules

Language is designed for clarity and reversibility.

Avoid words like best, top, recommended, or popularity-driven claims.
Avoid skill-judgment framing in the UI; focus on comfort and goals.
Every choice should feel reversible: review answers, edit, or restart.