046-scraping-the-billboard/docs/business-case.md

Business Case

Metadata

Key	Value
ID	BC-001
CrossReference	SA-001
Language	en
Domain	it

Version History

Date	Status	Author	Reviewer	Change	Commit
2026-10-28	Accepted	Jens Tirsvad Nielsen	AI as stand-in for S01	Initial version	01e016e

---

Executive Summary

Course participants of the Udemy "100 Days of Code" bootcamp (day 46, "Musical Time Machine") need a worked, runnable solution to the assignment: pick a date, scrape the Billboard Hot 100 chart of that date, and build a private YouTube Music playlist from it. This project delivers that solution as a small, readable Python 3.13 command line application with tests, documentation and a trilingual wiki (English, Danish, Bahasa Malaysia), so that fellow participants (S02) and repository viewers (S03) can read, run and learn from it.

Methodological and Standards Foundation

The project follows the software quality assurance (SQA) and quality control (QC) framework mounted at framework/ (plan-first gate, review against QC checklists). Design artifacts, where needed, follow Larman's Applying UML and Patterns. Quality is stated with the ISO/IEC (International Organization for Standardization and International Electrotechnical Commission) 25010:2023 characteristics. The code follows the clean-architecture and coding-conventions skills of the framework.

Problem Statement

• The assignment gives instructions in prose only; participants who get stuck on scraping, on the ytmusicapi browser authentication or on the playlist calls have no tested reference.
• The Billboard site can change or add a paywall at any time, so a reference must also work against the course's clone site, Bakeboard.
• Shared solutions are often a single untested script with no instructions to run it.

Business Opportunity

A documented, tested and screenshot-illustrated solution makes the assignment repeatable for other participants, and shows a clean way to structure a small scraping and API project. It is a portfolio item for S01.

Objectives

1. O1: Deliver an application that asks for a date (YYYY-MM-DD) and scrapes the 100 song titles and artists of that date from Bakeboard into a Python list.
2. O2: Authenticate to YouTube Music with ytmusicapi using a browser.json file and verify the connection by counting the library playlists.
3. O3: Create a private playlist named {date} Billboard 100, without creating a duplicate when it already exists.
4. O4: Search each song and add the top song result to the playlist, skipping failures without stopping.
5. O5: Provide automated tests, a README with setup, run and test instructions, a Doxygen configuration and a wiki in English, Danish and Bahasa Malaysia, with a screenshot for each lecture step.
6. O6: Publish the repository with a description and topics.

Scope

In Scope

• Python application in src/, tests in tests/, documents in docs/.
• Scraping of the Bakeboard clone site (https://appbrewery.github.io/bakeboard-hot-100/); the base URL is a constant so the real Billboard URL can be configured.
• YouTube Music authentication, playlist creation and song search through ytmusicapi.
• pyproject.toml, .venv instructions, constants.py, pytest tests, Doxygen comments and Doxyfile, README.md from the framework template.
• Wiki pages in en, da and ms, with a screenshot for each of the four lecture steps.
• Repository description and topics on the git host.

Out of Scope

• Spotify (the course path chosen is YouTube Music).
• Automating the creation of browser.json; it is a manual step of S01 and contains personal session cookies.
• A graphical user interface.
• Using the git host tokens in .env inside the application or its tests.

Expected Benefits

Tangible Benefits

• A runnable solution with a passing automated test suite.
• A README and a wiki in three languages that another participant can follow without help.

Intangible Benefits

• Better understanding of HTTP headers, HTML parsing and cookie-based API authentication.
• A clearer repository for viewers (S03).

Strategic Alignment

The project supports S01's goal of completing the bootcamp with portfolio-quality work, and the course community's habit of sharing and comparing solutions (S02, S03).

Success Criteria

#	Criterion	Target	Measure
1	Songs scraped for a valid Bakeboard date	100 titles with artists	Automated test on a stored copy of the page, plus one run against the live site
2	Automated tests	All pass; line coverage of src/ at least 85 %	python -m pytest
3	Duplicate playlist	0 duplicates after two runs with the same date	Test with a fake YouTube Music client
4	A failing song	Run continues and reports the skipped count	Test with a fake client that raises for one song
5	Runtime dependencies	At most 3: requests, beautifulsoup4, ytmusicapi	pyproject.toml
6	Documentation	README with setup, run and test sections; wiki pages in en, da, ms with 4 step screenshots each	File check in the milestone review
7	Repository metadata	Description and at least 5 topics set	Git host API response

Risks

Risk	Impact	Mitigation
The Bakeboard or Billboard page markup changes	Scraper returns no songs	Selectors are constants; the scraper raises a clear error on an empty result; tests use a stored page
browser.json is missing or its cookies have expired	Steps 2 to 4 cannot be run live	README documents how to renew it; the live steps are marked as needing S01; automated tests use a fake client
Personal cookies or tokens are committed	Account takeover	browser.json and .env are in .gitignore; the app and tests never read .env
ytmusicapi changes its interface	Playlist code breaks	The library is behind a port (an interface) and its version is bounded in pyproject.toml
Screenshots show personal data	Privacy loss	Screenshots are taken of terminal output and public pages, and checked before commit

Assumptions

• S01 has a Google account and Firefox, and will create browser.json by hand as the lecture describes.
• Python 3.13 or later is installed.
• The git host repository exists under the owner given by the origin remote, and the GITEA_TOKEN in .env may write to it.
• Reviews are done by the AI as stand-in for S01, as the autonomous mode of AGENTS.md allows.

Constraints

• Python 3.13 or later, a venv named .venv, pytest, constants in constants.py, configuration in pyproject.toml.
• Folder structure src/, tests/, docs/; Doxygen comments in the source.
• Runtime dependencies only where needed.
• One branch and one pull request per milestone, to keep track of the steps.
• Planned window: 2026-10-28 to 2026-11-30.
• The Product Owner's language is English and the domain is IT; the wiki is written in en, da and ms.

Cost–Benefit Assessment

Costs	Benefits
About 25 hours of S01's and AI time over five weeks; no licence or hosting cost	A reusable reference solution, a portfolio piece and a three-language learning wiki. The assessment is qualitative because the project has no revenue; its value is learning and sharing.

Stakeholders

Stakeholder ID (SA)	Interest in this project
S01	Completes the assignment; decides, builds and reviews
S02	Reads and runs the code and compares solutions
S03	Browses the repository for ideas

Recommendation

Proceed — the scope is small, the dependencies are few and the result is useful to all three stakeholders.

---