# 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.