Skip to main content

Guided Installer — Implementation Plan

Internal implementation record for the guided installer and compatibility wizard. Written before implementation; kept as the architecture reference.

Current architecture (audited)​

  • Framework: Docusaurus 3.10 (classic preset), TypeScript, React 19.
  • Hosting: static GitHub Pages at /ADL/, deployed by .github/workflows/deploy.yml on push to main. PR CI: build + typecheck (build.yml), markdownlint, link check.
  • Content: docs/ markdown with a global MDX component registry (src/theme/MDXComponents.ts), design system in src/css/custom.css, docs intelligence index (scripts/generate-docs-index.mjs → static/ai-metadata.json).
  • Existing compatibility platform: data/*.json (devices, hardware, matrix, test results, verified configurations) + typed components under src/components/Compatibility/. The wizard reuses its vocabularies (SupportLevel, VerificationLevel) but keeps its own richer device catalog so the existing matrix is untouched.
  • Search: @easyops-cn/docusaurus-search-local. Tests: none before this feature (typecheck + build only).

Constraints​

  • Static site; no backend, no accounts, no server-side state. All wizard state lives in localStorage (versioned) and optional exported JSON.
  • onBrokenLinks: "throw" — every route/link must exist at build time.
  • CLAUDE.md content rules: no duplicate documentation (link canonical pages), official sources only, beginner-first writing.
  • No force-push; feature developed on feature/guided-linux-installer and merged --no-ff into main.

Chosen approach​

  • Route: /get-started/ — a single React page (src/pages/get-started/) hosting the multi-step wizard, review screen, disclaimer gate, assessment result, and generated guide. No JS → <noscript> block links to the manual Quick Start and compatibility methodology pages.
  • Engine: pure functions in src/lib/compatibility/ — evaluate(answers) → AssessmentResult. No React imports; fully unit-testable. Every rule that changes an outcome emits a human-readable reason string. Scores are used only for ordering; explanations are factor-based.
  • Guide: src/lib/guide/ generates a step list from typed templates parameterized by distro/desktop/username/display/audio; user-controlled values pass an allowlist sanitizer. Every step carries an environment label, expected result, verification, failure symptoms, and recovery.
  • Data: JSON in data/ (consistent with the existing platform): device-catalog.json (variant-aware records with sources + evidence levels), wizard-issues.json (structured known-issue records), sources.json (source registry). Schema validation runs in CI via scripts/validate-wizard-data.mjs (zero-dependency, like the existing docs-index generator).
  • Scripts: static/downloads/scripts/*.sh + SHA256SUMS + a JSON manifest; regenerated by scripts/generate-script-checksums.mjs and verified in CI. ShellCheck runs in CI.
  • Tests: Vitest for the engine/guide/storage (fixtures include the 18 required scenarios); Playwright (already used in this repo's workflow) drives manual e2e verification of the wizard flow before merge.

Data model (summary)​

  • WizardAnswers — questionnaire state (device identity, hardware, objective, experience, display, keyboard, mouse, peripherals, audio, preferences), all optional-friendly with explicit unknown values.
  • DeviceRecord — manufacturer, marketing name, model numbers, regional variants, SoC by region, architecture, RAM/storage variants, USB connector/version, DisplayPort Alt Mode (true | false | "unknown"), manufacturer desktop mode, wireless display, Android versions, tested configurations, known issues, evidence level, sources, lastVerified.
  • AssessmentResult — overall status + confidence, per-dimension results (15 dimensions), recommendation (distro, desktop, display method, audio, browser, peripherals) each with reasons, required/optional warnings, alternatives, matched issues, evidence references.
  • Versioned: questionnaire schema, saved state, device report schema, disclaimer, rules, scripts. Saved state with an older version is migrated when trivially possible, otherwise reset with an explanatory message.

Compatibility policy (initial, labeled as ADL planning heuristics)​

  • RAM bands: <3 GB CLI-first; 3–4 GB lightweight DE with warnings; ~6 GB XFCE/MATE preferred; ≥8 GB XFCE/MATE/Plasma; GNOME experimental.
  • Storage bands: <6 GB free — no full desktop; 6–10 GB lightweight only; ≥12 GB preferred baseline; workloads add to the estimate.
  • Architecture: native ARM64 preferred; armv7/32-bit limited; QEMU cross-architecture marked advanced and not recommended by default.
  • Unknown devices are never marked incompatible — they get specification-based results with explicit confidence labels.
  • Missing wired video out (no DP Alt Mode) is not a blocker: the engine recommends phone-screen/wireless/VNC paths instead.

Routing and navigation plan​

  • New route /get-started (+ homepage CTA + navbar entry).
  • New KB pages under docs/get-started/ (start here, methodology, disclaimer), docs/learn/concepts/linux-on-android-explained.md, docs/learn/hardware/external-displays.md, docs/troubleshooting/symptom-index.md, docs/downloads/scripts.md. Existing canonical pages were extended instead of duplicated: docs/applications/browsers.md (Snap stubs, Mozilla repo, no --no-sandbox), docs/troubleshooting/audio.md (localhost ACL, Android 16 issue), and docs/compatibility/devices/galaxy-s22-plus.md (field report).
  • No existing URLs move; nothing is deleted.

Testing plan​

Unit (Vitest): engine fixtures (all 18 required scenarios), username sanitization, storage migration, report parsing, export/import round-trip. Data: JSON schema validation + checksum verification in CI. Shell: ShellCheck all scripts in CI. Manual e2e before merge: wizard completion on mobile + desktop viewports, S22+ path, unknown-device path, CLI-only path, disclaimer gating, resume after reload.

Migration and rollback​

Additive feature; no content moved. Rollback = git revert -m 1 <merge-commit-sha> (documented in docs/developer/guided-installer-rollback.md with the real SHAs).