steam-backlog-helper/docs/implementation-plan.md

Implementation Plan

Milestone 0: Repository Foundation

Goal: make the project ready for implementation.

Deliverables:

• Planning docs aligned with confirmed product decisions.
• AGENTS.md for coding-agent and contributor workflow.
• SECURITY.md for vulnerability handling and secret-management expectations.
• CONTRIBUTING.md for local development and contribution standards.
• CODE_OF_CONDUCT.md for open-source readiness.
• .gitignore suited for Tauri, SvelteKit, Rust, Node, and build artifacts.

Exit criteria:

• The repository explains what is in scope for the MVP.
• A new contributor can understand the intended stack and project rules.

Milestone 1: Application Skeleton

Goal: create the first runnable desktop application.

Deliverables:

• Tauri app scaffold using Steam Backlog Helper as the display name and com.boris.backloghelper as the package ID. Initial shell complete.
• Svelte/SvelteKit frontend with TypeScript. Initial shell complete.
• Basic app shell with setup, picker, and settings routes or views. Setup and picker shell complete; settings route pending.
• Lint, format, typecheck, and test commands. Typecheck and build scripts complete; formatting and test scripts pending.
• Initial SQLite migration system.

Exit criteria:

• The app runs locally in development mode.
• The app can open a desktop window.
• CI can run linting and typechecks.

Milestone 2: Steam Setup And Library Import

Goal: import a user's Steam library through supported API access.

Deliverables:

• Steam profile input supporting Steam ID, vanity URL, or profile URL.
• User-provided Steam Web API key setup.
• Owned-games fetch.
• Store metadata lookup during import to identify Steam app type.
• Default exclusion of tools, DLC, demos, soundtracks, and other non-game app types.
• Library cache in SQLite.
• Clear failure states for invalid keys, private profiles, rate limits, and network failures.

Exit criteria:

• A public/API-accessible Steam library can be imported and refreshed.
• Imported games persist after app restart.
• No real API keys are logged or committed.

Milestone 3: Metadata Enrichment

Goal: make recommendations useful beyond raw ownership and playtime.

Deliverables:

• Steam Store metadata lookup for images, genres, categories, and release data.
• Public review-score signal where available.
• HowLongToBeat-compatible completion-time integration after validation.
• Metadata cache with freshness timestamps.
• Default filtering for demos, tools, soundtracks, and DLC.
• Single-player and multiplayer/co-op category detection.

Exit criteria:

• Recommendation candidates include playtime, image, genre/category, review, and completion-time data where available.
• Metadata lookup failures degrade gracefully.

Milestone 4: Recommendation Engine

Goal: produce explainable, useful recommendations.

Deliverables:

• Short-question recommendation flow.
• Weighted scoring using available time, optional genre, completion preference, review score, and playtime.
• Hard eligibility filters for candidate removal.
• Preferred filters for review signal, single-player/multiplayer, genre, and playtime weighting.
• True-random toggle that bypasses weighted scoring.
• Dynamic shortlist output.
• Human-readable recommendation explanations.
• Unit tests for scoring behavior.

Exit criteria:

• Recommendation behavior is deterministic under seeded test data.
• True-random mode is separate from weighted recommendations.
• Edge cases such as empty candidate sets have clear UI states.

Milestone 5: Picker Experience

Goal: make the primary workflow feel focused and polished.

Deliverables:

• Recommendation-first home screen.
• Spinning-wheel reveal for the primary recommendation.
• Keyboard-accessible controls.
• Steam app ID launch links.
• Responsive desktop layout for common window sizes.

Exit criteria:

• A keyboard-only user can complete setup and run a recommendation.
• The chosen game can be opened in Steam.
• The picker remains usable without a full library-management screen.

Milestone 6: Packaging And Releases

Goal: produce installable desktop artifacts.

Deliverables:

• Windows 10+ build.
• macOS 26+ build, with self-signing where practical.
• Linux AppImage build.
• Gitea runner workflows for x86 builds.
• Local arm64 build instructions.
• Release artifact checklist.

Exit criteria:

• Release artifacts can be generated from the repository.
• The release process is documented for personal Gitea.