Add the plan baseline: business case, stakeholders, plan, design and milestones

Business Case, Stakeholder Analysis, Project Plan, use case chain (UCD, US, UC, DM, SSD, OC, SD, DCD, DICT), three ADRs, milestones MIL-001 to MIL-007, the traceability matrix and 22 review records (autonomous mode, AI as stand-in for S01).
2026-10-14 21:33:25 +08:00
parent 97eec837a4
commit c3fbcbcfaf
49 changed files with 3484 additions and 0 deletions
@@ -0,0 +1,52 @@
+# ADR-0001: Standard library first, speech as an optional extra
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | ADR-0001 |
+| CrossReference | [BC-001], [SA-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | pending |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+The assignment tells the participant to read the word list with `pandas`. The Product Owner (S01) also wants the Malay word spoken, which needs `gTTS` and `playsound`. GitHub viewers (S03) want no runtime dependencies, and fellow course participants (S02) want a program they can run at once. Options:
+
+1. `pandas` for CSV and `gTTS` plus `playsound` as normal dependencies: matches the assignment text, but installs a large dependency tree for a 1000 row file, and a failing `playsound` build breaks the install.
+2. Standard library `csv` for the data and `gTTS` plus `playsound` as an optional extra behind a port: no runtime dependency for the core program, speech available on request.
+3. No speech at all: simplest, but does not meet the Product Owner's wish.
+
+## Decision
+
+The core program uses only the Python standard library (`csv`, `tkinter`, `random`, `pathlib`). Speech is an optional extra declared as `speech` in `pyproject.toml` (`pip install -e ".[speech]"`), used through a `SpeechPort`, and replaced by a silent adapter when the extra or the network is missing.
+
+## Consequences
+
+**Positive:**
+
+- `dependencies` in `pyproject.toml` is empty, which meets success criterion 3 of [BC-001] and the concern of S03.
+- The program and its tests run without a network.
+- A broken audio player cannot stop the program from starting.
+
+**Negative:**
+
+- The code differs from the assignment text, which uses `pandas`; the wiki explains the mapping for S02.
+- Two code paths exist for speech (real and silent) and both need tests.
+- `playsound` is unmaintained and is pinned to 1.2.2.
+
+## Affected Artifacts
+
+- [BC-001] — success criterion 3 and the risk about `playsound`
+- [SA-001] — the conflict between S01 and S03
+
+---
+
+[BC-001]: ../business-case.md
+[SA-001]: ../stakeholder-analysis.md
@@ -0,0 +1,53 @@
+# ADR-0002: Clean architecture with MVVM for the Tkinter program
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | ADR-0002 |
+| CrossReference | [BC-001], [DM-001], [DCD-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | pending |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+The assignment solution is a single script with global variables (`current_card`, `to_learn`, `flip_timer`). The project's coding standard (QC-PY-001, criteria 14 to 17) asks for layers that point inward, ports for external services and a presentation pattern. The program is small, so a full layering has a cost in files. Options:
+
+1. One module with the assignment's globals: closest to the course, but behaviour cannot be tested without a display and rules are mixed with Tkinter.
+2. The four layers (domain, application, infrastructure, presentation) with MVVM: behaviour is testable, the assignment's function names live on in the view and view model.
+3. Layers without a view model: the view would hold the rules again.
+
+## Decision
+
+The program is built in four layers under `src/flash_card/` with MVVM in the presentation layer. The function names of the assignment (`next_card`, `flip_card`, `is_known`) are kept on the view and on the view model, and the names `current_card` and `flip_timer` are kept where the concept exists (`StudySession.current_card`, `FlashCardView.flip_timer`); the course's `to_learn` list is the `Deck`.
+
+## Consequences
+
+**Positive:**
+
+- The rules (draw, remove, persist) are tested without Tkinter or a file system.
+- Replacing the CSV file or the speech service touches one adapter.
+- The wiki can map each assignment step to the file that implements it.
+
+**Negative:**
+
+- More files than the course solution; a beginner needs the wiki's map to find the assignment's code.
+- Layer boundaries need discipline (DTO at the boundary, one composition root).
+
+## Affected Artifacts
+
+- [DM-001] — concepts refined by the domain layer
+- [DCD-001] — the class design this ADR constrains
+- [BC-001] — objective 5, step by step delivery
+
+---
+
+[BC-001]: ../business-case.md
+[DM-001]: ../domain-model.md
+[DCD-001]: ../dcd.md
@@ -0,0 +1,52 @@
+# ADR-0003: Artifact types skipped for this project
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | ADR-0003 |
+| CrossReference | [BC-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | pending |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+The framework lists more artifact types than a one-week, single-person learning project needs. The journey of the `create-project` skill makes the baseline (`BC`, `SA`, `PP`, `MIL`) mandatory and every other type optional, but requires the reason for a skipped step to be recorded. Options: (1) create every type, which doubles the documents for one person and a 1000 word program; (2) create the baseline, the use case chain the code is traced to (`UCD`, `US`, `UC`, `DM`, `SSD`, `OC`, `SD`, `DCD`, `DICT`) and skip the types that add no information here.
+
+## Decision
+
+Option 2 is chosen. These types are not created in this project, for the reasons given:
+
+| Type | Reason |
+| --- | --- |
+| `KPI`, `BMC`, `BPMN` | One owner, no revenue and no business process; the measurable success criteria are in the Business Case |
+| `RA` | The idea is not a hunch: the assignment specifies the behaviour, so there is no belief to test before the Business Case |
+| `GOV` | One person owns, builds and approves; the review workflow is the framework's own and the autonomous mode records stand-in reviews |
+| `ERD` | The only persistence is two CSV files with the same two columns, described in the adapters of the Design Class Diagram |
+| `TRN`, `TRR` | No reviewer training for a single-person project |
+
+## Consequences
+
+**Positive:**
+
+- Less documentation to keep in step for a small program.
+- Reviews concentrate on the documents that carry the decisions.
+
+**Negative:**
+
+- A later contributor finds no governance document; the review records show who stood in.
+- If persistence grows beyond a CSV file, an `ERD` must be added in that change.
+
+## Affected Artifacts
+
+- [BC-001] — the success criterion on review coverage counts only created artifacts
+
+---
+
+[BC-001]: ../business-case.md