Updated Ex14 lab files and instructions

Author: ChrisHowd

DownloadableCodeProjects/standalone-lab-projects/sdd-get-started-rss-feed/StakeholderDocuments/AppFeatures.md

@@ -1,9 +1,41 @@
-
 # App features
 
 This RSS feed reader is designed around three themes: making it easy to subscribe to sources, making it easy to keep up with new items, and giving you control so your feed doesn’t become overwhelming.
 
-## Must have features (single-user, local-only)
+## MVP cutline (deliver first)
+
+The MVP is the smallest end-to-end slice that proves the core workflow (subscribe → fetch → store → read) with minimal moving parts.
+
+For the MVP, the app MUST:
+
+- Let a user add a feed subscription by pasting a feed URL (and remove it later).
+- Let a user manually refresh a feed and see a newest-first list of items.
+- Let a user open an item’s original link.
+- Store subscriptions and items locally so they remain available after restart.
+- Show clear per-feed errors (fetch/parse/etc.) without crashing.
+
+For the MVP, the app MAY:
+
+- Render item content as plain text only (title + summary) to reduce early complexity.
+- Treat duplicate items as a later hardening step (best-effort is acceptable initially).
+
+## MVP behavior rules (defaults)
+
+To keep behavior predictable and avoid “mystery waiting”, the MVP follows a few simple rules:
+
+- Refresh is manual: clicking “refresh now” fetches the selected feed immediately.
+- The system should not fetch a feed repeatedly in a tight loop. If a feed was refreshed very recently, the backend should throttle additional refresh attempts.
+- Network calls must have timeouts so one slow feed does not stall the system.
+
+In MVP these values are not user-configurable; they can be hard-coded:
+
+- Manual refresh throttle per feed: 60 seconds
+- HTTP request timeout: 10 seconds
+- Max concurrent feed fetches: 5
+
+Background polling and scheduling are intentionally post-MVP.
+
+## V1 scope (post-MVP, single-user, local-only)
 
 At a minimum, the app will let a single user subscribe to RSS/Atom feeds, fetch updates, and read items with a clean read/unread workflow. Subscriptions can be managed directly, including removing feeds you no longer want.
 
@@ -17,30 +49,81 @@ Reliability and safety are part of the must-haves. The app should handle common
 
 Finally, the app will support basic organization by allowing feeds to be grouped into folders/collections (for example: News, Tech, Work).
 
-### MVP (build this first)
+### Website-to-feed discovery behavior (post-MVP)
+
+When a user pastes a website URL (not a direct feed URL), the system should attempt to discover the site’s RSS/Atom feed by:
+
+- Following redirects.
+- Looking for standard feed link tags in the HTML (for example `<link rel="alternate">` RSS/Atom entries).
+
+If discovery fails, the UI should tell the user a feed could not be found and suggest pasting a direct feed URL.
+
+### De-duplication behavior
 
-For the first working version, we will focus on a small subset that proves the end-to-end flow:
+The system should avoid storing the same item multiple times within a feed. For the MVP, best-effort de-duplication is acceptable; stronger guarantees are post-MVP.
 
-Users can subscribe to a feed by URL, remove a subscription, and manually refresh a feed to pull in new items. The backend will also poll feeds periodically in the background.
+When computing identity:
 
-The app stores feeds and items locally and shows a per-feed list of items (newest first). Users can mark items read/unread and mark all as read per feed. Users can open the original article link. The app handles common feed errors without crashing, and it avoids storing duplicate items.
+- Prefer a stable unique identifier from the feed (GUID/id) when present.
+- Otherwise fall back to a reasonable composite (for example link + published date).
 
-For the MVP, we are intentionally keeping scope tight. We will not build accounts, sync, notifications, OPML import/export, or advanced filtering rules until the core reader experience is stable.
+### HTTP caching optimization (optional)
+
+If a feed returns caching headers (ETag / Last-Modified), the backend may use conditional requests to reduce bandwidth. This is an optimization and not required for the MVP.
+
+### MVP (build this first)
+
+For the first working version, we will focus on the MVP cutline described above.
+
+Sequencing: deliver the manual end-to-end flow first (subscribe → refresh → items). Only once that success-path works reliably should we add discovery, background polling, read/unread, folders, and other “daily use” features.
+
+For the MVP, we are intentionally keeping scope tight. We will not build accounts, sync, notifications, OPML import/export, advanced filtering rules, background polling, discovery, folders, or read/unread until the core reader experience is stable.
 
 ### MVP definition of done
 
 The MVP is complete when the following are true:
 
 - A user can add a feed by URL and remove it later.
 - A user can refresh a feed on demand and see newly fetched items.
-- The backend polls feeds in the background on a schedule.
 - Items are stored locally and remain available after restarting the app.
 - The UI shows items per feed in newest-first order.
 - A user can open the original article link.
-- A user can mark items as read and mark all items as read for a feed.
-- The app avoids creating duplicate entries for the same item.
 - Feed failures show clear errors and do not crash the app.
 
+The following are explicitly post-MVP (V1) features:
+
+- Background polling
+- Website-to-feed discovery
+- Read/unread and mark-all-read
+- Folders/collections
+- Strong de-duplication guarantees
+
+## Practical notes for running the MVP (developer-facing)
+
+- The UI and API run on different localhost ports; that is expected. The UI must be configured with the API base URL.
+- Items appear only after a refresh has successfully run at least once for that subscription.
+- Feed URLs should be treated as user input: trim whitespace and normalize before storing to avoid hard-to-debug issues (for example, a trailing space).
+
+## Practical verification flow (developer-facing)
+
+Use at least one known-good feed for the first success-path verification before trying stricter or rate-limited sources.
+
+Example “known-good” feeds:
+
+- <https://devblogs.microsoft.com/dotnet/feed/>
+- <https://devblogs.microsoft.com/visualstudio/feed/>
+- <https://devblogs.microsoft.com/powershell/feed/>
+
+Golden path:
+
+1. Start the API and UI.
+2. Add the feed URL.
+3. Click refresh.
+4. Verify items appear newest-first.
+5. Open an item’s original link.
+
+Some popular sources may block or rate-limit automated clients (commonly returning 403/429 or HTML instead of RSS). Treat those as robustness tests, not the first success-path test.
+
 ## Nice to have features
 
 Once the core reader experience is stable, we can improve organization and reading flow with tags/labels, saved/starred (“read later”) items, and strong keyboard shortcuts. We can also offer multiple layouts (compact list, magazine/cards, etc.) so users can choose how dense the UI feels.
@@ -64,4 +147,3 @@ Notifications can be added later for high-priority feeds or keyword matches.
 Integrations and sharing features can come later as well. This includes sharing items to email and chat tools (for example Slack/Teams), sending items to read-later services (for example Pocket/Instapaper/OneNote), and offering quick actions like copying a clean link. It can also include opening links in the system browser or in an in-app browser view. For some workflows, RSS-to-email could be added so selected feeds (or filtered items) are forwarded to an email inbox.
 
 Finally, as privacy and data ownership features mature, we can explicitly focus on minimal tracking and clear data ownership/export (for example, ensuring users can always export their data in a usable form).
-

DownloadableCodeProjects/standalone-lab-projects/sdd-get-started-rss-feed/StakeholderDocuments/MVPSystemRules.md

@@ -16,9 +16,38 @@ Multi-device sync, first-class mobile support, and expanded offline capabilities
 
 ## Delivery approach
 
-Development will follow a spec-driven workflow using GitHub Spec Kit. Each meaningful slice of work should have a lightweight spec that describes the user outcome, acceptance criteria, and any important edge cases (for example, malformed feeds or duplicate items).
+We will build in small increments, validating behavior at each step, rather than attempting a large implementation in a single pass.
 
-We will build in small increments, validating behavior at each step, rather than attempting a large implementation in a single pass. Specs will guide implementation order and help keep scope under control.
+Each increment should be described in a short, testable way:
+
+- One primary user outcome.
+- A handful of acceptance scenarios (a clear success-path plus 2–3 high-value failures).
+- The edge cases we are *not* solving yet.
+
+To keep delivery fast and predictable:
+
+- Start with the smallest end-to-end MVP slice first (manual subscribe → refresh → items).
+- Treat discovery, background polling, folders, and read/unread as post-MVP unless explicitly pulled in.
+- Use a known-good feed for the first success-path verification before testing stricter or rate-limited sources.
+- Keep work items small and single-purpose; when a change affects behavior, add/adjust tests first.
+
+When writing a work breakdown (tasks):
+
+- Prefer tasks that touch one file or one concern.
+- If a task changes multiple concerns, split it.
+- Put test changes first for each behavior change.
+- If you use a marker for parallelizable tasks (for example `[P]`), only mark tasks that do not touch the same files.
+- Keep local dev ports and base URLs explicit and configurable to avoid unnecessary debugging churn.
+
+## What "MVP working" means in practice
+
+For the first MVP slice, "working" should be validated on a known-good RSS/Atom feed with this flow:
+
+1. Add subscription
+2. Trigger manual refresh
+3. View items
+
+Only after this success-path works reliably should we use stricter sites (rate-limited/blocked sources) as robustness tests.
 
 ## Rollout plan
 
@@ -47,15 +76,17 @@ Local data should remain the user’s data. The design should make it easy to ke
 - **Reliability**: Handle malformed/redirected feeds robustly; deduplicate items idempotently; persist safely to avoid corruption.
 - **Observability**: Use structured logs with levels; surface actionable error messages; collect minimal opt-in telemetry only.
 - **Release Management**: Use semantic versioning; maintain a changelog; ensure reproducible builds; enable quick rollback.
-- **Documentation & Process**: Keep README/user guide and architecture overview current; write brief specs with acceptance criteria via Spec Kit; definition of done includes tests, docs, and QA checklist.
+- **Documentation & Process**: Keep README/user guide and architecture overview current; write brief requirements with acceptance criteria; definition of done includes tests, docs, and a short QA checklist.
 - **Dependency Management**: Pin versions; update regularly; track licenses; generate an SBOM (e.g., CycloneDX) and verify compliance.
 
+## “MVP first” rule of thumb
+
+If a requirement introduces background scheduling, concurrency orchestration, or cross-cutting UI state (examples: polling, folders, read/unread), it is probably post-MVP unless the app cannot demonstrate the core workflow without it.
+
 ## How this document fits with the others
 
 This document describes the project at a high level and sets constraints, methodology, and rollout expectations.
 
-Detailed, user-facing requirements live in [App Features.md](App%20Features.md).
-
-The technology choices and architectural rationale live in [Tech Stack.md](Tech%20Stack.md).
+Detailed, user-facing requirements live in [AppFeatures.md](AppFeatures.md).
 
-MVP system behavior rules that inform our specs live in [MVP System Rules.md](MVP%20System%20Rules.md).
+The technology choices and architectural rationale live in [TechStack.md](TechStack.md).