Add 11.3 System Thinking section (spec 02) - #914
Open
HexSleeves wants to merge 4 commits into
Open
Conversation
… 1.0) Adds Chapter 11.3 System Thinking main content page with intro, learning objectives, diagram type explanations (sequence/component/ data flow), and a diagramming tools comparison. Includes the simple-system example app (Flask frontend + Flask backend + SQLite), its PlantUML source diagrams and rendered PNGs, an architecture README template, and Exercise 1 instructions. Verified end-to-end via docker compose: add/list/toggle tasks all work. Frontend is published on host port 8080 instead of 5000 because macOS AirPlay Receiver silently intercepts port 5000.
…ation exercise content (Tasks 2.0-4.0) Adds transaction tracing methodology, the "Add to Cart" worked example, ADR/README/presentation teaching content, Exercises 2-4, and optional advanced extensions to 11.3-system-thinking.md. Adds supporting templates (ADR, presentation, tracing, self-assessment), the integration-example deliverable set, and the OTel Demo setup guide with a pinned release, requirements, troubleshooting, and an optional trimmed docker-compose subset. ARM validation is documented as pending, not yet run live. Also adds a cspell word list to package.json (project had none) covering technical terms introduced by this content plus pre-existing false positives (e.g. "bootcamp", "chartjs") needed for the pre-commit hook to pass at all.
…/spec status Adds the 11.3 sidebar entry under Chapter 11, refreshes docs/README.md's consolidated front-matter record via the pre-commit condenser, checks off completed task-list items in Spec 02, and updates Spec 02's status in the Chapter 11 parent spec to reflect content-complete with OTel Demo ARM validation still pending. Also extends the cspell config to exclude docs/specs/** (mirroring the existing markdownlint exclusion) and recognize other pre-existing technical terms and a few longstanding typos across docs/README.md and docs/_sidebar.md, since the spell-check hook had never actually been exercised against those files' full content until this commit touched them.
Contributor
📝 WalkthroughWalkthroughAdded Chapter 11 system-thinking content with runnable Flask/SQLite and OpenTelemetry Demo examples, architecture diagrams, ADR and presentation templates, exercises, documentation navigation, and completion-status updates. ChangesSystem Thinking Chapter
Estimated code review effort: 3 (Moderate) | ~25 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Author
|
Reviewer note: this PR adds a repo-level Also: the OTel Demo local ARM validation is documented as pending in 🤖 Generated with Claude Code |
This was referenced Jul 23, 2026
Author
HexSleeves
marked this pull request as ready for review
July 31, 2026 15:46
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 13
🧹 Nitpick comments (1)
examples/ch11/templates/adr-example-multiple-databases.md (1)
3-15: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winPin the OpenTelemetry Demo revision used for this ADR.
This example makes implementation-specific claims about the cart and feature flag datastores, but it does not identify the Demo release or commit used for the analysis. Add the revision and links to the relevant service or configuration files. This keeps the worked example reproducible when the upstream demo changes.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@examples/ch11/templates/adr-example-multiple-databases.md` around lines 3 - 15, Update the ADR metadata or context to identify the exact OpenTelemetry Demo release or commit analyzed, and add links to the cart and feature flag service or datastore configuration files supporting the claims in the Decision section. Keep the existing datastore rationale unchanged while making the referenced upstream revision reproducible.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/11-application-development/11.3-system-thinking.md`:
- Around line 109-113: Replace the Markdown image links with HTML img elements
referencing the corresponding assets under the root /img/ directory, preserving
each image’s existing alt text, centered styling, and width of 700.
- Around line 160-180: Update the repository-local Markdown links in
11.3-system-thinking.md, including the example, template, and diagram references
identified by the review, to use paths relative to this page instead of absolute
/examples/... paths. Preserve the existing link targets and visible text while
ensuring every affected link resolves correctly from
docs/11-application-development/.
In `@examples/ch11/otel-demo-setup/docker-compose-subset.yml`:
- Around line 24-27: Record ARM validation as completed across all referenced
documentation: in examples/ch11/otel-demo-setup/docker-compose-subset.yml lines
24-27, replace the pending warning with the completed result and note any
subset-specific workflow not tested; in
docs/specs/00-spec-chapter-11-appdev/00-spec-chapter-11-appdev.md lines 16,
121-127, and 450, mark Spec 02 complete, replace pending-validation language
with evidence, and align the priority; in
docs/specs/02-spec-system-thinking/02-tasks-system-thinking.md lines 169 and
200-201, remove the deferred-validation claim and complete task 4.18 or state
the exact remaining unverified workflow.
In `@examples/ch11/otel-demo-setup/README.md`:
- Line 66: Update the README setup example so the suggested ENVOY_PORT value
does not conflict with the documented default ENVOY_ADMIN_PORT=8081; recommend
8082, or explicitly instruct users to change both port variables together.
In `@examples/ch11/simple-system/backend/app.py`:
- Around line 75-80: Update the task toggle flow around the SELECT/UPDATE
statements to use a single atomic SQL UPDATE that derives the next done value in
the database. Preserve the 404 response when no task matches, and obtain the
updated done state from that same statement or transaction before returning the
response.
In `@examples/ch11/simple-system/backend/Dockerfile`:
- Around line 1-7: Create a dedicated non-root application user in both
Dockerfiles before CMD, grant that user ownership and write access to /app and
/data in examples/ch11/simple-system/backend/Dockerfile lines 1-7, and ownership
and write access to /app in examples/ch11/simple-system/frontend/Dockerfile
lines 1-8. Add USER directives so each Flask process runs as the dedicated user.
In `@examples/ch11/simple-system/diagrams/component.puml`:
- Around line 25-30: Update the Backend note in the component diagram to
document the frontend’s POST /tasks/<task_id>/toggle endpoint alongside the
existing task routes, using the API contract defined by frontend/app.py.
In `@examples/ch11/simple-system/diagrams/dataflow.puml`:
- Around line 16-17: Update examples/ch11/simple-system/diagrams/dataflow.puml
lines 16-17 to separate the POST /tasks 201 response, frontend 302 redirect,
browser GET / request, backend GET /tasks request, and list response before
rendered HTML. Update examples/ch11/simple-system/diagrams/sequence.puml lines
23-32 to show the browser follow-up GET / as a distinct hop, keeping the 302
redirect response separate from the final rendered HTML response.
In `@examples/ch11/simple-system/frontend/app.py`:
- Around line 24-34: Update the add_task and toggle_task routes to inspect each
backend POST response before redirecting. For non-success responses, return a
user-visible error response instead of redirecting; preserve the existing
redirect only when the mutation succeeds.
In `@examples/ch11/simple-system/frontend/templates/index.html`:
- Around line 18-29: Update the forms in the template: add an associated label
for the new-task input, give each task toggle button a task-specific accessible
label, and add aria-pressed reflecting task.done while preserving the existing
visual [x]/[ ] text.
In `@examples/ch11/templates/adr-example-grpc.md`:
- Around line 11-15: Update the decision statement around “Use gRPC” to scope
gRPC and .proto contracts to synchronous service-to-service RPC communication
only. Explicitly identify Kafka-based or other event-driven asynchronous flows
as an exception, while preserving the existing HTTP/JSON boundary for
browser-facing traffic.
In `@examples/ch11/templates/presentation-outline.md`:
- Around line 3-29: Adjust the section timings in the presentation outline so
their maximum values sum to no more than 15 minutes, while preserving the
five-section structure and keeping the total walkthrough within the stated 10–15
minute target.
In `@package.json`:
- Around line 75-77: Correct the source typos “equivillant,” “leanred,” and
“pathes” in the referenced documentation and corresponding generated
docs/README.md entries, then remove these three words from the spellchecker
allowlist in package.json. Ensure the corrected documentation remains consistent
with the generated README content.
---
Nitpick comments:
In `@examples/ch11/templates/adr-example-multiple-databases.md`:
- Around line 3-15: Update the ADR metadata or context to identify the exact
OpenTelemetry Demo release or commit analyzed, and add links to the cart and
feature flag service or datastore configuration files supporting the claims in
the Decision section. Keep the existing datastore rationale unchanged while
making the referenced upstream revision reproducible.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: fde3111d-feeb-4eab-83ff-38487f1b7f3f
⛔ Files ignored due to path filters (7)
docs/11-application-development/img11/integration-example-component.pngis excluded by!**/*.pngdocs/11-application-development/img11/integration-example-dataflow.pngis excluded by!**/*.pngdocs/11-application-development/img11/integration-example-sequence.pngis excluded by!**/*.pngdocs/11-application-development/img11/otel-transaction-trace.pngis excluded by!**/*.pngdocs/11-application-development/img11/simple-system-component.pngis excluded by!**/*.pngdocs/11-application-development/img11/simple-system-dataflow.pngis excluded by!**/*.pngdocs/11-application-development/img11/simple-system-sequence.pngis excluded by!**/*.png
📒 Files selected for processing (40)
docs/11-application-development/11.3-system-thinking.mddocs/README.mddocs/_sidebar.mddocs/specs/00-spec-chapter-11-appdev/00-spec-chapter-11-appdev.mddocs/specs/02-spec-system-thinking/02-tasks-system-thinking.mdexamples/ch11/integration-example/README.mdexamples/ch11/integration-example/adr-example.mdexamples/ch11/integration-example/diagrams/component.pumlexamples/ch11/integration-example/diagrams/dataflow.pumlexamples/ch11/integration-example/diagrams/sequence.pumlexamples/ch11/integration-example/presentation-outline.mdexamples/ch11/otel-demo-setup/README.mdexamples/ch11/otel-demo-setup/diagrams/add-to-cart-trace.pumlexamples/ch11/otel-demo-setup/docker-compose-subset.ymlexamples/ch11/simple-system/.gitignoreexamples/ch11/simple-system/README.mdexamples/ch11/simple-system/backend/Dockerfileexamples/ch11/simple-system/backend/app.pyexamples/ch11/simple-system/backend/pyproject.tomlexamples/ch11/simple-system/backend/requirements.txtexamples/ch11/simple-system/diagrams/component.pumlexamples/ch11/simple-system/diagrams/dataflow.pumlexamples/ch11/simple-system/diagrams/sequence.pumlexamples/ch11/simple-system/docker-compose.ymlexamples/ch11/simple-system/frontend/Dockerfileexamples/ch11/simple-system/frontend/app.pyexamples/ch11/simple-system/frontend/pyproject.tomlexamples/ch11/simple-system/frontend/requirements.txtexamples/ch11/simple-system/frontend/templates/index.htmlexamples/ch11/templates/adr-example-frontend-ssr.mdexamples/ch11/templates/adr-example-grpc.mdexamples/ch11/templates/adr-example-multiple-databases.mdexamples/ch11/templates/adr-template.mdexamples/ch11/templates/architecture-readme-template.mdexamples/ch11/templates/integration-self-assessment.mdexamples/ch11/templates/presentation-outline.mdexamples/ch11/templates/presentation-rubric.mdexamples/ch11/templates/readme-enhancement-checklist.mdexamples/ch11/templates/transaction-tracing-template.mdpackage.json
Comment on lines
+109
to
+113
|  | ||
|
|
||
|  | ||
|
|
||
|  |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use HTML images from /img/.
Replace the Markdown image syntax with <img> elements. Move or reference the rendered assets through the root /img/ directory. Keep the existing alt text and dimensions.
Also applies to: 252-252
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/11-application-development/11.3-system-thinking.md` around lines 109 -
113, Replace the Markdown image links with HTML img elements referencing the
corresponding assets under the root /img/ directory, preserving each image’s
existing alt text, centered styling, and width of 700.
Source: Coding guidelines
Comment on lines
+160
to
+180
| The target application lives in [`examples/ch11/simple-system/`](/examples/ch11/simple-system/) — a task list app with a Flask frontend, a Flask backend API, and a SQLite database. Its own README explains what it does; read that first. | ||
|
|
||
| ```bash | ||
| cd examples/ch11/simple-system | ||
| docker compose up --build | ||
| ``` | ||
|
|
||
| Once both services report healthy, open <http://localhost:8080>, add a few tasks, and toggle one done. Poke at the backend directly too: | ||
|
|
||
| ```bash | ||
| curl http://localhost:5001/tasks | ||
| curl -X POST http://localhost:5001/tasks -H "Content-Type: application/json" -d '{"title": "Trace this request"}' | ||
| ``` | ||
|
|
||
| ### Task | ||
|
|
||
| 1. **Read the code** — `frontend/app.py`, `backend/app.py`, and the templates. Don't just skim; trace what happens when you submit the "add task" form, from the browser to SQLite and back. | ||
| 2. **Create a sequence diagram** for "add a task" showing every hop: browser → frontend → backend → database → backend → frontend → browser. | ||
| 3. **Create a component diagram** showing the three components, their responsibilities, and the protocol used between each pair (HTTP, SQL). | ||
| 4. **Create a data flow diagram** for "add a task" showing how the data's *shape* changes at each step (form data → JSON → SQL row → JSON → HTML). | ||
| 5. **Document the architecture** in a README using the [architecture README template](/examples/ch11/templates/architecture-readme-template.md). |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
Replace absolute local links with paths relative to this page.
Links such as /examples/ch11/... depend on the Docsify deployment root. Use relative paths from docs/11-application-development/11.3-system-thinking.md for every repository-local template, example, and diagram link.
Also applies to: 203-203, 262-262, 272-272, 307-311, 322-322, 337-337, 347-347, 355-362, 383-393
🧰 Tools
🪛 LanguageTool
[style] ~179-~179: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...sed between each pair (HTTP, SQL). 4. Create a data flow diagram for "add a task" ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/11-application-development/11.3-system-thinking.md` around lines 160 -
180, Update the repository-local Markdown links in 11.3-system-thinking.md,
including the example, template, and diagram references identified by the
review, to use paths relative to this page instead of absolute /examples/...
paths. Preserve the existing link targets and visible text while ensuring every
affected link resolves correctly from docs/11-application-development/.
Source: Coding guidelines
Comment on lines
+24
to
+27
| # Not validated against a live run in this environment — see "Local ARM | ||
| # validation: pending" in README.md. If frontend fails to start because of an | ||
| # unmet dependency, fall back to `docker-compose.minimal.yml` or the full | ||
| # `docker-compose.yml` instead. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Update the validation status consistently.
The PR context states that ARM validation completed in commit 460d21b, but these files still state that it is pending or intentionally deferred. Record the completed validation. Retain only limitations that the completed validation did not cover.
examples/ch11/otel-demo-setup/docker-compose-subset.yml#L24-L27: replace the pending-validation warning with the completed validation result, and distinguish full-stack validation from any untested subset-specific workflow.docs/specs/00-spec-chapter-11-appdev/00-spec-chapter-11-appdev.md#L16-L16: mark Spec 02 as complete if the completed validation satisfies its final acceptance condition.docs/specs/00-spec-chapter-11-appdev/00-spec-chapter-11-appdev.md#L121-L127: replace the pending ARM-validation note with the completed validation evidence.docs/specs/00-spec-chapter-11-appdev/00-spec-chapter-11-appdev.md#L450-L450: align the priority status with the completed validation.docs/specs/02-spec-system-thinking/02-tasks-system-thinking.md#L169-L169: remove the claim that live validation remains intentionally deferred.docs/specs/02-spec-system-thinking/02-tasks-system-thinking.md#L200-L201: complete task 4.18 or document the exact remaining unverified workflow.
📍 Affects 3 files
examples/ch11/otel-demo-setup/docker-compose-subset.yml#L24-L27(this comment)docs/specs/00-spec-chapter-11-appdev/00-spec-chapter-11-appdev.md#L16-L16docs/specs/00-spec-chapter-11-appdev/00-spec-chapter-11-appdev.md#L121-L127docs/specs/00-spec-chapter-11-appdev/00-spec-chapter-11-appdev.md#L450-L450docs/specs/02-spec-system-thinking/02-tasks-system-thinking.md#L169-L169docs/specs/02-spec-system-thinking/02-tasks-system-thinking.md#L200-L201
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@examples/ch11/otel-demo-setup/docker-compose-subset.yml` around lines 24 -
27, Record ARM validation as completed across all referenced documentation: in
examples/ch11/otel-demo-setup/docker-compose-subset.yml lines 24-27, replace the
pending warning with the completed result and note any subset-specific workflow
not tested; in docs/specs/00-spec-chapter-11-appdev/00-spec-chapter-11-appdev.md
lines 16, 121-127, and 450, mark Spec 02 complete, replace pending-validation
language with evidence, and align the priority; in
docs/specs/02-spec-system-thinking/02-tasks-system-thinking.md lines 169 and
200-201, remove the deferred-validation claim and complete task 4.18 or state
the exact remaining unverified workflow.
| | Load generator | `/loadgen/` | | ||
| | Feature flag UI (flagd) | `/feature` | | ||
|
|
||
| The base port is configurable — set `ENVOY_PORT=8081` (or any free port) before `docker compose up` if 8080 is already taken on your machine. |
Contributor
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Use a non-conflicting port in the setup example.
Line 66 recommends ENVOY_PORT=8081, while Line 92 documents ENVOY_ADMIN_PORT=8081 by default. Following the example without changing the admin port binds two host ports to 8081 and fails. Use 8082 or instruct users to change both variables.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@examples/ch11/otel-demo-setup/README.md` at line 66, Update the README setup
example so the suggested ENVOY_PORT value does not conflict with the documented
default ENVOY_ADMIN_PORT=8081; recommend 8082, or explicitly instruct users to
change both port variables together.
Comment on lines
+75
to
+80
| row = db.execute("SELECT id, done FROM tasks WHERE id = ?", (task_id,)).fetchone() | ||
| if row is None: | ||
| return jsonify({"error": "task not found"}), 404 | ||
|
|
||
| new_done = 0 if row["done"] else 1 | ||
| db.execute("UPDATE tasks SET done = ? WHERE id = ?", (new_done, task_id)) |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Make the task-state transition atomic.
Separate SELECT and UPDATE statements let concurrent toggle requests read the same done value and write the same next value. Two toggles can leave the task toggled only once.
Use one SQL UPDATE that derives done in the database. Return the updated state from the same statement or transaction.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@examples/ch11/simple-system/backend/app.py` around lines 75 - 80, Update the
task toggle flow around the SELECT/UPDATE statements to use a single atomic SQL
UPDATE that derives the next done value in the database. Preserve the 404
response when no task matches, and obtain the updated done state from that same
statement or transaction before returning the response.
Comment on lines
+24
to
+34
| @app.post("/tasks") | ||
| def add_task(): | ||
| title = request.form.get("title", "") | ||
| requests.post(f"{BACKEND_URL}/tasks", json={"title": title}, timeout=5) | ||
| return redirect(url_for("index")) | ||
|
|
||
|
|
||
| @app.post("/tasks/<int:task_id>/toggle") | ||
| def toggle_task(task_id): | ||
| requests.post(f"{BACKEND_URL}/tasks/{task_id}/toggle", timeout=5) | ||
| return redirect(url_for("index")) |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== Locate files =="
fd -a 'app.py|backend|requirements|docker|compose' . | sed 's#^\./##' | head -200
echo
echo "== frontend app.py =="
if [ -f examples/ch11/simple-system/frontend/app.py ]; then
cat -n examples/ch11/simple-system/frontend/app.py
fi
echo
echo "== Search backend task API =="
rg -n "tasks|toggle|@.*route|400|404|raise_error|json" examples/ch11/simple-system -S || trueRepository: liatrio/engineering-bootcamp
Length of output: 10095
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== backend task handlers =="
sed -n '1,90p' examples/ch11/simple-system/backend/app.py
echo
echo "== frontend templates =="
find examples/ch11/simple-system/frontend/templates -type f -print -exec sh -c 'echo "--- $1"; cat -n "$1"' sh {} \;
echo
echo "== deterministic backend response shape for edge inputs =="
python3 - <<'PY'
# Read the source text and extract the relevant status/error outcomes from
# examples/ch11/simple-system/backend/app.py without importing Flask or running repo code.
from pathlib import Path
src = Path("examples/ch11/simple-system/backend/app.py").read_text()
checks = {
"POST /tasks uses empty-title 400": 'if "title" not in data or not data["title"].strip():' in src and 'return jsonify({"error": "title is required"}), 400' in src,
"POST /tasks/<int:task_id>/toggle uses missing task 404": 'if row is None:' in src and 'return jsonify({"error": "task not found"}), 404' in src,
"frontend add_task ignores status": 'requests.post(f"{BACKEND_URL}/tasks", json={"title": title}, timeout=5)\n return redirect(url_for("index"))' in src,
"frontend toggle_task ignores status": 'requests.post(f"{BACKEND_URL}/tasks/{task_id}/toggle", timeout=5)\n return redirect(url_for("index"))' in src,
}
for name, ok in checks.items():
print(f"{name}: {ok}")
PYRepository: liatrio/engineering-bootcamp
Length of output: 4175
Handle backend mutation failures before redirecting.
POST /tasks can return 400 for an empty title and POST /tasks/<task_id>/toggle can return 404 for a missing task. Check the backend response status in both frontend routes and return a user-visible error instead of redirecting as if the mutation succeeded.
🧰 Tools
🪛 ast-grep (0.45.0)
[warning] 26-26: Request-controlled URL passed to requests; validate against an allowlist to prevent SSRF.
Context: requests.post(f"{BACKEND_URL}/tasks", json={"title": title}, timeout=5)
Note: [CWE-918] Server-Side Request Forgery (SSRF).
(ssrf-requests)
[warning] 32-32: Request-controlled URL passed to requests; validate against an allowlist to prevent SSRF.
Context: requests.post(f"{BACKEND_URL}/tasks/{task_id}/toggle", timeout=5)
Note: [CWE-918] Server-Side Request Forgery (SSRF).
(ssrf-requests)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@examples/ch11/simple-system/frontend/app.py` around lines 24 - 34, Update the
add_task and toggle_task routes to inspect each backend POST response before
redirecting. For non-success responses, return a user-visible error response
instead of redirecting; preserve the existing redirect only when the mutation
succeeds.
Comment on lines
+18
to
+29
| <form action="/tasks" method="post"> | ||
| <input type="text" name="title" placeholder="New task" required> | ||
| <button type="submit">Add</button> | ||
| </form> | ||
|
|
||
| <ul> | ||
| {% for task in tasks %} | ||
| <li class="{{ 'done' if task.done else '' }}"> | ||
| <form action="/tasks/{{ task.id }}/toggle" method="post" style="display:inline"> | ||
| <button type="submit" style="border:none;background:none;cursor:pointer;"> | ||
| {{ '[x]' if task.done else '[ ]' }} | ||
| </button> |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Add accessible labels to both form controls.
Line 19 has no associated <label>. Lines 26-29 give each toggle button only [x] or [ ] as its accessible name. Add an input label, a task-specific toggle label, and aria-pressed for the current state.
Proposed accessibility update
+ <label for="new-task">New task</label>
- <input type="text" name="title" placeholder="New task" required>
+ <input id="new-task" type="text" name="title" placeholder="New task" required>
- <button type="submit" style="border:none;background:none;cursor:pointer;">
+ <button type="submit" aria-label="{{ 'Mark incomplete' if task.done else 'Mark complete' }}: {{ task.title }}" aria-pressed="{{ 'true' if task.done else 'false' }}" style="border:none;background:none;cursor:pointer;">📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| <form action="/tasks" method="post"> | |
| <input type="text" name="title" placeholder="New task" required> | |
| <button type="submit">Add</button> | |
| </form> | |
| <ul> | |
| {% for task in tasks %} | |
| <li class="{{ 'done' if task.done else '' }}"> | |
| <form action="/tasks/{{ task.id }}/toggle" method="post" style="display:inline"> | |
| <button type="submit" style="border:none;background:none;cursor:pointer;"> | |
| {{ '[x]' if task.done else '[ ]' }} | |
| </button> | |
| <form action="/tasks" method="post"> | |
| <label for="new-task">New task</label> | |
| <input id="new-task" type="text" name="title" placeholder="New task" required> | |
| <button type="submit">Add</button> | |
| </form> | |
| <ul> | |
| {% for task in tasks %} | |
| <li class="{{ 'done' if task.done else '' }}"> | |
| <form action="/tasks/{{ task.id }}/toggle" method="post" style="display:inline"> | |
| <button type="submit" aria-label="{{ 'Mark incomplete' if task.done else 'Mark complete' }}: {{ task.title }}" aria-pressed="{{ 'true' if task.done else 'false' }}" style="border:none;background:none;cursor:pointer;"> | |
| {{ '[x]' if task.done else '[ ]' }} | |
| </button> |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@examples/ch11/simple-system/frontend/templates/index.html` around lines 18 -
29, Update the forms in the template: add an associated label for the new-task
input, give each task toggle button a task-specific accessible label, and add
aria-pressed reflecting task.done while preserving the existing visual [x]/[ ]
text.
Comment on lines
+11
to
+15
| The OTel Demo is composed of ~15 backend services written in a deliberately wide mix of languages (Go, .NET, Java, Python, Node.js, Rust, C++, Ruby, Kotlin, PHP) to demonstrate OpenTelemetry instrumentation across ecosystems. These services need to call each other constantly and synchronously — the frontend calls the cart service, the checkout service calls product catalog, currency, shipping, payment, and email services, and so on. With that many polyglot services, two problems show up immediately: (1) without a shared contract, it's easy for services to drift on request/response shapes as they evolve independently, and (2) JSON-over-HTTP works but has real serialization overhead when a single user action can trigger a dozen internal calls. | ||
|
|
||
| ## Decision | ||
|
|
||
| Use gRPC, with `.proto` files as the shared source of truth for service contracts, for all internal (service-to-service) communication. External-facing traffic (browser to frontend) remains plain HTTP/JSON, since browsers don't speak gRPC natively. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Scope the decision to synchronous RPC communication.
The statement that gRPC handles “all internal” communication is inaccurate for the demo material. The chapter also teaches Kafka-based asynchronous paths. State that gRPC is the contract for synchronous service RPCs, and identify event-driven flows as an exception.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@examples/ch11/templates/adr-example-grpc.md` around lines 11 - 15, Update the
decision statement around “Use gRPC” to scope gRPC and .proto contracts to
synchronous service-to-service RPC communication only. Explicitly identify
Kafka-based or other event-driven asynchronous flows as an exception, while
preserving the existing HTTP/JSON boundary for browser-facing traffic.
Comment on lines
+3
to
+29
| A suggested structure for a 10-15 minute technical walkthrough of a system you've analyzed. Adjust timing to fit your material, but keep the whole thing inside the 10-15 minute target — see the [presentation rubric](presentation-rubric.md) for how this gets evaluated. | ||
|
|
||
| ## 1. Introduction (1-2 min) | ||
|
|
||
| - What system or feature are you presenting? | ||
| - Why does it matter / what problem does it solve for the user? | ||
|
|
||
| ## 2. System Overview (2-3 min) | ||
|
|
||
| - Show your **component diagram** | ||
| - Explain the high-level architecture: what are the major pieces, and what does each one own? | ||
|
|
||
| ## 3. Deep Dive (5-7 min) | ||
|
|
||
| - Show your **sequence diagram** | ||
| - Walk through one complete transaction, step by step, service by service | ||
| - Call out the interesting parts: an unexpected hop, an async boundary, a data transformation, a place where things could fail | ||
|
|
||
| ## 4. Trade-offs and Alternatives (2-3 min) | ||
|
|
||
| - What are the pros and cons of how this was built? | ||
| - What else could have been done instead, and why wasn't it? | ||
| - Reference an ADR if you wrote one for this system | ||
|
|
||
| ## 5. Q&A (2-3 min) | ||
|
|
||
| - Be ready for follow-up questions about decisions and details |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the outline fit the stated 10-15 minute limit.
The maximum durations total 18 minutes: 2 + 3 + 7 + 3 + 3. This conflicts with the 10-15 minute target in this file and in examples/ch11/templates/presentation-rubric.md. Reduce the ranges so their upper bounds total no more than 15 minutes.
Proposed timing adjustment
-## 3. Deep Dive (5-7 min)
+## 3. Deep Dive (4-5 min)
...
-## 4. Trade-offs and Alternatives (2-3 min)
+## 4. Trade-offs and Alternatives (1-2 min)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| A suggested structure for a 10-15 minute technical walkthrough of a system you've analyzed. Adjust timing to fit your material, but keep the whole thing inside the 10-15 minute target — see the [presentation rubric](presentation-rubric.md) for how this gets evaluated. | |
| ## 1. Introduction (1-2 min) | |
| - What system or feature are you presenting? | |
| - Why does it matter / what problem does it solve for the user? | |
| ## 2. System Overview (2-3 min) | |
| - Show your **component diagram** | |
| - Explain the high-level architecture: what are the major pieces, and what does each one own? | |
| ## 3. Deep Dive (5-7 min) | |
| - Show your **sequence diagram** | |
| - Walk through one complete transaction, step by step, service by service | |
| - Call out the interesting parts: an unexpected hop, an async boundary, a data transformation, a place where things could fail | |
| ## 4. Trade-offs and Alternatives (2-3 min) | |
| - What are the pros and cons of how this was built? | |
| - What else could have been done instead, and why wasn't it? | |
| - Reference an ADR if you wrote one for this system | |
| ## 5. Q&A (2-3 min) | |
| - Be ready for follow-up questions about decisions and details | |
| A suggested structure for a 10-15 minute technical walkthrough of a system you've analyzed. Adjust timing to fit your material, but keep the whole thing inside the 10-15 minute target — see the [presentation rubric](presentation-rubric.md) for how this gets evaluated. | |
| ## 1. Introduction (1-2 min) | |
| - What system or feature are you presenting? | |
| - Why does it matter / what problem does it solve for the user? | |
| ## 2. System Overview (2-3 min) | |
| - Show your **component diagram** | |
| - Explain the high-level architecture: what are the major pieces, and what does each one own? | |
| ## 3. Deep Dive (4-5 min) | |
| - Show your **sequence diagram** | |
| - Walk through one complete transaction, step by step, service by service | |
| - Call out the interesting parts: an unexpected hop, an async boundary, a data transformation, a place where things could fail | |
| ## 4. Trade-offs and Alternatives (1-2 min) | |
| - What are the pros and cons of how this was built? | |
| - What else could have been done instead, and why wasn't it? | |
| - Reference an ADR if you wrote one for this system | |
| ## 5. Q&A (2-3 min) | |
| - Be ready for follow-up questions about decisions and details |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@examples/ch11/templates/presentation-outline.md` around lines 3 - 29, Adjust
the section timings in the presentation outline so their maximum values sum to
no more than 15 minutes, while preserving the five-section structure and keeping
the total walkthrough within the stated 10–15 minute target.
Comment on lines
+75
to
+77
| "equivillant", | ||
| "leanred", | ||
| "pathes" |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -nP '\b(equivillant|leanred|pathes)\b' \
-g '*.md' \
-g '!node_modules/**' \
-g '!**/.venv/**'Repository: liatrio/engineering-bootcamp
Length of output: 166
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'package.json lines 60-85:\n'
sed -n '60,85p' package.json
printf '\nAll tracked files containing spellcheck/cspell config:\n'
git ls-files | rg '(^|/)(cspell\.json|cspell\.jsonc|\.cspellrc|cspell\.config|\.cspellrc\.)' || true
printf '\nSearch all tracked text files for exact words across repository (excluding common generated dirs):\n'
rg -nP '\b(equivillant|leanred|pathes)\b' \
-g '!node_modules/**' \
-g '!dist/**' \
-g '!build/**' \
-g '!package-lock.json' \
. || trueRepository: liatrio/engineering-bootcamp
Length of output: 1790
Fix the source typos instead of whitelisting them.
equivillant, leanred, and pathes still appear in docs/6-software-development-practices/6.6-hello-devops.md:8, docs/6-software-development-practices/6.4-pairprogramming.md:8, docs/9-kubernetes-container-orchestration/9.8.1-kustomize.md:19, and generated docs/README.md entries. Correct those occurrences, then remove the matching entries from package.json so future content is spell checked.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@package.json` around lines 75 - 77, Correct the source typos “equivillant,”
“leanred,” and “pathes” in the referenced documentation and corresponding
generated docs/README.md entries, then remove these three words from the
spellchecker allowlist in package.json. Ensure the corrected documentation
remains consistent with the generated README content.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Chapter 11.3 (System Thinking & Codebase Analysis) to the bootcamp, per Spec 02.
Content (
docs/11-application-development/11.3-system-thinking.md):Examples & templates (
examples/ch11/):simple-system/— a minimal 3-service Flask/SQLite task-list app for Exercise 1 (tested end-to-end withdocker compose up)otel-demo-setup/— setup guide for the OpenTelemetry Demo Application, pinned to release2.1.3, with system requirements, troubleshooting, and an optional trimmeddocker-compose-subset.ymlintegration-example/— a complete worked example (Product Recommendation Flow) modeling the depth expected for the capstone exercisetemplates/— architecture README, ADR (+ 3 worked examples), transaction tracing, presentation outline/rubric, and integration self-assessment templatesIntegration:
docs/README.mdvianpm run refresh-front-matternpm run lint(markdownlint) and the cspell pre-commit hook pass repo-wideWhat remains
Per the recovery instructions for this branch, live validation of the OTel Demo setup on Apple Silicon (ARM) was intentionally not run in this environment. The setup guide's ARM instructions (using the upstream
.env.arm64workaround) are sourced from the official OTel Demo documentation, but are marked "Local ARM validation: pending" inexamples/ch11/otel-demo-setup/README.mdand in the Spec 02 status until someone runs the full stack end-to-end on real ARM hardware and confirms/corrects the guidance.Test plan
docker compose up --buildinexamples/ch11/simple-system/— verified working end-to-end (add/view/toggle tasks)plantuml/plantumlDocker image and embedded with alt textnpm run lint— 0 issuesSummary by CodeRabbit