README.md

@@ -25,6 +25,18 @@ The repository holds one small module per lecture step.
 
 Doxygen comments in the source describe every public name; `Doxyfile` builds them into `docs/doxygen/`.
 
+### Lecture steps
+
+Each lecture has its own screenshot in `docs/images/` (made by `docs/images/capture.py` with a headless browser, so no window opens on your desktop) and a wiki page that explains what the lecture taught.
+
+**Lecture 1: frontend, backend and the request-response cycle.** The client asks, the Flask server prepares the answer, the database supplies data.
+
+![Lecture 1: client, server and database](docs/images/lecture-01.png)
+
+**Lecture 2: the first Flask server.** `hello.py` serves "Hello, World!" from the home route. Start it with `flask --app flask_day_54.presentation.hello run` (or set `FLASK_APP`: `export FLASK_APP=flask_day_54.presentation.hello` on macOS and Linux, `$env:FLASK_APP = "flask_day_54.presentation.hello"` in PowerShell, `set FLASK_APP=flask_day_54.presentation.hello` in Command Prompt, then `flask run`).
+
+![Lecture 2: Hello, World! in the browser](docs/images/lecture-02.png)
+
 ## 📋 Requirements
 
 - Python 3.13 or newer, because the project sets `requires-python = ">=3.13"` in `pyproject.toml`.

docs/artifact-registry.md

@@ -18,7 +18,7 @@ document of a type. `Primary File` may contain a glob (e.g.
 | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0002 |
 | DICT | Domain Dictionary | docs/dictionary.md | 002 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 016 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 017 |
 
 ## Languages
 

docs/images/capture.py

@@ -0,0 +1,214 @@
+"""Create the lecture screenshots in docs/images/ without touching the desktop.
+
+Every screenshot is taken by a headless Edge or Chrome (no window, no mouse, no
+keyboard). Terminal screenshots render the real output of real commands.
+
+Usage (from the repository root, with the project's .venv active):
+    python docs/images/capture.py 1 2 3 4 5 6
+"""
+# Developer tool only (not shipped in the package): every command it runs is a fixed list
+# built from constants, sys.executable and local paths; it reads no external input.
+
+import html
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+OUT = ROOT / "docs" / "images"
+SOURCES = OUT / "sources"
+BROWSERS = [
+    r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe",
+    r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+    "microsoft-edge",
+    "google-chrome",
+    "chromium",
+]
+PORT = 5057
+APP = "flask_day_54.presentation.hello"
+
+TERMINAL_CSS = """
+body{margin:0;background:#1e1e1e;font-family:Consolas,'DejaVu Sans Mono',monospace;color:#d4d4d4}
+.bar{background:#333;color:#ccc;padding:8px 14px;font-size:14px}
+pre{margin:0;padding:16px 18px;font-size:15px;line-height:1.45;white-space:pre-wrap}
+.p{color:#6a9955}.c{color:#9cdcfe}
+"""
+
+BROWSER_CSS = """
+body{margin:0;background:#f3f3f3;font-family:Segoe UI,Arial,sans-serif}
+.tab{background:#dde3ea;padding:8px 14px;font-size:13px;color:#333}
+.url{background:#fff;margin:8px;padding:6px 12px;border:1px solid #bbb;border-radius:14px;font-size:14px}
+.page{background:#fff;height:150px;padding:16px;font-size:16px;font-family:Times New Roman,serif}
+"""
+
+
+def find_browser() -> str:
+    for candidate in BROWSERS:
+        found = shutil.which(candidate) or (candidate if os.path.exists(candidate) else None)
+        if found:
+            return found
+    raise SystemExit("No Edge or Chrome found for headless screenshots")
+
+
+def shot(page: Path, png: Path, width: int, height: int) -> None:
+    """Take a headless screenshot of a local page or a URL."""
+    target = page.as_uri() if isinstance(page, Path) else page
+    profile = tempfile.mkdtemp(prefix="shot-")
+    subprocess.run(  # nosemgrep
+        [
+            find_browser(),
+            "--headless=new",
+            "--disable-gpu",
+            "--hide-scrollbars",
+            f"--user-data-dir={profile}",
+            f"--window-size={width},{height}",
+            f"--screenshot={png}",
+            "--virtual-time-budget=3000",
+            target,
+        ],
+        check=True,
+        capture_output=True,
+        timeout=60,
+    )
+    shutil.rmtree(profile, ignore_errors=True)
+    print("wrote", png.relative_to(ROOT))
+
+
+def run(cmd: list[str], cwd: Path, timeout: int = 30) -> str:
+    done = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout)  # nosemgrep
+    return (done.stdout + done.stderr).rstrip("\n")
+
+
+def terminal_page(title: str, entries: list[tuple[str, str]], png: Path, height: int) -> None:
+    """Render (command, output) pairs as a terminal and take the screenshot."""
+    lines = []
+    for command, output in entries:
+        lines.append(f'<span class="p">$</span> <span class="c">{html.escape(command)}</span>')
+        if output:
+            lines.append(html.escape(output))
+    page = (
+        f"<!doctype html><meta charset='utf-8'><style>{TERMINAL_CSS}</style>"
+        f"<div class='bar'>{html.escape(title)}</div><pre>" + "\n".join(lines) + "</pre>"
+    )
+    SOURCES.mkdir(exist_ok=True)
+    src = SOURCES / (png.stem + ".html")
+    src.write_text(page, encoding="utf-8")
+    shot(src, png, 900, height)
+
+
+def python() -> str:
+    return sys.executable
+
+
+def step1() -> None:
+    shot(SOURCES / "lecture-01.html", OUT / "lecture-01.png", 900, 400)
+
+
+def start_server() -> subprocess.Popen:
+    proc = subprocess.Popen(  # nosemgrep
+        [python(), "-m", "flask", "--app", APP, "run", "--port", str(PORT)],
+        cwd=ROOT,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+    )
+    for _ in range(40):
+        try:
+            urllib.request.urlopen(f"http://127.0.0.1:{PORT}/", timeout=1).read()
+            return proc
+        except OSError:
+            time.sleep(0.25)  # nosemgrep
+    proc.kill()
+    raise SystemExit("server did not start")
+
+
+def step2() -> None:
+    proc = start_server()
+    try:
+        body = urllib.request.urlopen(f"http://127.0.0.1:{PORT}/", timeout=3).read().decode()
+        page = (
+            f"<!doctype html><meta charset='utf-8'><style>{BROWSER_CSS}</style>"
+            f"<div class='tab'>127.0.0.1:5057</div>"
+            f"<div class='url'>http://127.0.0.1:{PORT}/</div>"
+            f"<div class='page'>{body}</div>"
+        )
+        src = SOURCES / "lecture-02.html"
+        src.write_text(page, encoding="utf-8")
+        shot(src, OUT / "lecture-02.png", 700, 230)
+    finally:
+        proc.kill()
+
+
+def step3() -> None:
+    work = Path(tempfile.mkdtemp(prefix="cli-demo-"))
+    bash = shutil.which("bash") or "bash"
+    entries = []
+    script = [
+        "pwd",
+        "ls",
+        "mkdir my_project",
+        "cd my_project && touch hello.py && ls",
+        "cd .. && rm -rf my_project && ls",
+    ]
+    for command in script:
+        output = run([bash, "-c", command], work)
+        entries.append((command, output.replace(str(work).replace("\\", "/"), "~/demo")))
+    shutil.rmtree(work, ignore_errors=True)
+    terminal_page("Terminal - lecture 3: the command line", entries, OUT / "lecture-03.png", 330)
+
+
+def step4() -> None:
+    entries = []
+    cmd = "python -m flask_day_54.domain.name_demo"
+    entries.append((cmd, run([python(), "-m", "flask_day_54.domain.name_demo"], ROOT)))
+    imp = "python -c \"import flask_day_54.domain.name_demo as m; print(m.describe_name(m.__name__))\""
+    entries.append(
+        (
+            imp,
+            run(
+                [
+                    python(),
+                    "-c",
+                    "import flask_day_54.domain.name_demo as m; print(m.describe_name(m.__name__))",
+                ],
+                ROOT,
+            ),
+        )
+    )
+    server = subprocess.Popen(  # nosemgrep
+        [python(), "-m", "flask_day_54.presentation.hello"],
+        cwd=ROOT,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+    )
+    time.sleep(3)  # nosemgrep
+    server.kill()
+    out = (server.stdout.read() if server.stdout else "").strip()
+    entries.append(("python -m flask_day_54.presentation.hello", out + "\n^C"))
+    terminal_page("Terminal - lecture 4: __name__ and __main__", entries, OUT / "lecture-04.png", 560)
+
+
+def step5() -> None:
+    module = "flask_day_54.domain.first_class_functions"
+    entries = [(f"python -m {module}", run([python(), "-m", module], ROOT))]
+    terminal_page("Terminal - lecture 5: functions as first-class objects", entries, OUT / "lecture-05.png", 420)
+
+
+def step6() -> None:
+    module = "flask_day_54.domain.decorators"
+    entries = [(f"python -m {module}", run([python(), "-m", module], ROOT))]
+    terminal_page("Terminal - lecture 6: decorators and the @ syntax", entries, OUT / "lecture-06.png", 380)
+
+
+STEPS = {1: step1, 2: step2, 3: step3, 4: step4, 5: step5, 6: step6}
+
+if __name__ == "__main__":
+    os.environ["PYTHONPATH"] = str(ROOT / "src")
+    for number in [int(a) for a in sys.argv[1:]] or STEPS:
+        STEPS[number]()

docs/images/sources/lecture-01.html

@@ -0,0 +1,36 @@
+<!doctype html>
+<meta charset="utf-8">
+<style>
+  body{margin:0;background:#fff;font-family:Segoe UI,Arial,sans-serif;color:#1f2933}
+  h1{font-size:20px;margin:14px 20px 0}
+  svg{display:block;margin:0 auto}
+  text{font-family:Segoe UI,Arial,sans-serif}
+</style>
+<h1>Lecture 1: frontend, backend and the request-response cycle</h1>
+<svg viewBox="0 0 860 380" width="860" height="380" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <marker id="a" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#1f2933"/></marker>
+  </defs>
+  <rect x="20" y="40" width="220" height="180" rx="10" fill="#e8f1fb" stroke="#2b6cb0" stroke-width="2"/>
+  <text x="130" y="72" text-anchor="middle" font-size="18" font-weight="600">Client (frontend)</text>
+  <text x="130" y="100" text-anchor="middle" font-size="14">Browser: HTML, CSS, JS</text>
+  <text x="130" y="140" text-anchor="middle" font-size="13" fill="#555">Restaurant: dining area</text>
+  <rect x="320" y="40" width="220" height="180" rx="10" fill="#e9f7ee" stroke="#2f855a" stroke-width="2"/>
+  <text x="430" y="72" text-anchor="middle" font-size="18" font-weight="600">Server (backend)</text>
+  <text x="430" y="100" text-anchor="middle" font-size="14">Python + Flask</text>
+  <text x="430" y="140" text-anchor="middle" font-size="13" fill="#555">Restaurant: kitchen</text>
+  <rect x="620" y="40" width="220" height="180" rx="10" fill="#fdf3e3" stroke="#b7791f" stroke-width="2"/>
+  <text x="730" y="72" text-anchor="middle" font-size="18" font-weight="600">Database</text>
+  <text x="730" y="100" text-anchor="middle" font-size="14">Stores the data</text>
+  <text x="730" y="140" text-anchor="middle" font-size="13" fill="#555">Restaurant: pantry</text>
+  <line x1="240" y1="90" x2="318" y2="90" stroke="#1f2933" stroke-width="2" marker-end="url(#a)"/>
+  <text x="280" y="82" text-anchor="middle" font-size="13">1 request</text>
+  <line x1="540" y1="90" x2="618" y2="90" stroke="#1f2933" stroke-width="2" marker-end="url(#a)"/>
+  <text x="580" y="82" text-anchor="middle" font-size="13">2 query</text>
+  <line x1="618" y1="170" x2="542" y2="170" stroke="#1f2933" stroke-width="2" marker-end="url(#a)"/>
+  <text x="580" y="190" text-anchor="middle" font-size="13">3 data</text>
+  <line x1="318" y1="170" x2="242" y2="170" stroke="#1f2933" stroke-width="2" marker-end="url(#a)"/>
+  <text x="280" y="190" text-anchor="middle" font-size="13">4 response</text>
+  <text x="430" y="280" text-anchor="middle" font-size="16">Request-response cycle: the client asks, the server prepares, the database supplies.</text>
+  <text x="430" y="312" text-anchor="middle" font-size="14" fill="#555">Flask is the framework that decides how the server part is structured.</text>
+</svg>

docs/images/sources/lecture-02.html

@@ -0,0 +1,6 @@
+<!doctype html><meta charset='utf-8'><style>
+body{margin:0;background:#f3f3f3;font-family:Segoe UI,Arial,sans-serif}
+.tab{background:#dde3ea;padding:8px 14px;font-size:13px;color:#333}
+.url{background:#fff;margin:8px;padding:6px 12px;border:1px solid #bbb;border-radius:14px;font-size:14px}
+.page{background:#fff;height:150px;padding:16px;font-size:16px;font-family:Times New Roman,serif}
+</style><div class='tab'>127.0.0.1:5057</div><div class='url'>http://127.0.0.1:5057/</div><div class='page'>Hello, World!</div>

docs/sqa/reviews/rc-016-code-mil-002-hello-flask.md

@@ -0,0 +1,62 @@
+# Review of MIL-002
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-016 |
+| CrossReference | [MIL-002], [QC-PY-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-11-06 | Proposed | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f97d647] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-002]
+- Checklist used: [QC-PY-001]
+- Scope: full review of the source and tests delivered by MIL-002 (src/, tests/)
+- Language and domain: n/a
+- Language reviewer: none (the reviewer reads English and knows the IT domain)
+- Mode: autonomous, not independent (AI as stand-in for S01)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | Modules, functions and constants use snake_case / UPPER_SNAKE; classes none or PascalCase. |
+| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names follow the lecture and the domain dictionary. |
+| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff format` leaves files unchanged and `ruff check` (E, F, I, B, UP) passes; configured in pyproject.toml. |
+| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | Every function signature is annotated, including `-> None`. |
+| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | No bare except and no swallowed exception. |
+| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults; no builtin shadowed. |
+| 7 | Files, locks and connections are managed with context managers | N-A | No file, lock or connection is opened. |
+| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | Module and public names carry docstrings plus Doxygen comments. |
+| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | Pass | print and logging are not used; no secrets handled. |
+| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | N-A | No DCD exists in this project; the layered layout is recorded in ADR-0001. |
+| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | pytest tests named for behaviour; no order or network dependence. |
+| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | N-A | No type checker is configured (optional criterion). |
+| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | Dependencies are declared in pyproject.toml; none unused (Flask is the optional `web` extra). |
+| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | Each constant is defined once in the constants.py of its layer. |
+| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | `domain` imports no framework or outer layer; imports point inward; no cycles. |
+| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | Small modules with one reason to change; no type tests or subclass hierarchies. |
+| 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | Layers domain, application, infrastructure, presentation under src/flask_day_54; tests in unit and e2e (ADR-0001); no layer merged. |
+| 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | English snake_case file names without spaces. |
+
+## Overall Verdict
+
+Go — All applicable mandatory criteria pass.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | S01 | - |
+
+---
+
+[MIL-002]: ../../milestones/mil-002-hello-flask.md
+[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
+[f97d647]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/054-flask/commit/f97d64766e4d49ebbbe2cef3b5c9c6ac1590f2b7

src/flask_day_54/application/get_greeting.py

@@ -0,0 +1,12 @@
+## @file get_greeting.py
+#  @brief Use case that provides the greeting.
+"""Use case that provides the greeting."""
+
+from flask_day_54.domain.constants import GREETING
+
+
+## @brief Return the greeting to show the user.
+#  @return The greeting text.
+def get_greeting() -> str:
+    """Return the greeting to show the user."""
+    return GREETING

src/flask_day_54/presentation/hello.py

@@ -0,0 +1,18 @@
+## @file hello.py
+#  @brief The minimal Flask application of lectures 1 and 2.
+"""The minimal Flask application of lectures 1 and 2."""
+
+from flask import Flask
+
+from flask_day_54.application.get_greeting import get_greeting
+
+## @brief The Flask application object.
+app = Flask(__name__)
+
+
+## @brief Handle GET / and answer with the greeting.
+#  @return The greeting as the response body.
+@app.route("/")
+def hello_world() -> str:
+    """Answer the root route with the greeting."""
+    return get_greeting()

tests/e2e/test_hello_app.py

@@ -0,0 +1,26 @@
+import pytest
+
+flask = pytest.importorskip("flask")
+
+
+def _client() -> "flask.testing.FlaskClient":
+    from flask_day_54.presentation.hello import app
+
+    return app.test_client()
+
+
+def test_root_returns_greeting_when_get() -> None:
+    response = _client().get("/")
+
+    assert response.status_code == 200
+    assert response.get_data(as_text=True) == "Hello, World!"
+
+
+def test_unknown_path_returns_404() -> None:
+    assert _client().get("/missing").status_code == 404
+
+
+def test_root_content_type_is_html() -> None:
+    response = _client().get("/")
+
+    assert response.content_type.startswith("text/html")

tests/unit/test_get_greeting.py

@@ -0,0 +1,5 @@
+from flask_day_54.application.get_greeting import get_greeting
+
+
+def test_get_greeting_returns_hello_world() -> None:
+    assert get_greeting() == "Hello, World!"