Skip to content

Tour Guide

Guide Maps

graph LR
  family["Python Programming"]
  program["Python Object-Oriented Programming"]
  guide["Capstone docs"]
  section["Docs"]
  page["Tour Guide"]
  proof["Proof route"]

  family --> program --> guide --> section --> page
  page -.checks against.-> proof
flowchart LR
  orient["Read the guide boundary"] --> inspect["Inspect the named files, targets, or artifacts"]
  inspect --> run["Run the confirm, demo, selftest, or proof command"]
  run --> compare["Compare output with the stated contract"]
  compare --> review["Return to the course claim with evidence"]

This guide explains the capstone as a narrative, not only as a file tree. Read it before or after running make demo. Use make tour when you want this narrative captured as a bundle instead of only printed once in the terminal.

Keep DOMAIN_GUIDE.md nearby if you want the fixed rules, samples, and expected outputs visible while following the story.

Scenario route

  1. Create one monitoring policy.
  2. Register rules while they are still in draft state.
  3. Activate the rules deliberately.
  4. Observe metric samples through the application surface.
  5. Let the runtime publish alerts and update downstream views.
  6. Inspect the resulting summary, active rule index, and open incidents.

What to notice at each step

Scenario step Main question Best surface to compare
create policy which object becomes authoritative first application.py and model.py
register rules who accepts or rejects rule setup model.py and lifecycle tests
activate rules where lifecycle permission actually lives tests/test_policy_lifecycle.py
observe samples which boundary evaluates behavior versus coordinates flow runtime.py and policies.py
publish incidents which outputs are derived rather than authoritative read_models.py and projections.py
inspect snapshot which inspection route best shows current state PROOF_GUIDE.md

Best command route

  1. Run make demo when you want the narrative directly in the terminal.
  2. Run make tour when you want walkthrough.txt, the local guide set, and a stable manifest for review.
  3. Compare the walkthrough bundle with ARCHITECTURE.md and WALKTHROUGH_GUIDE.md.

The current demo output is intentionally staged: it prints policy creation, rule registration, activation, sample observation, and derived-state inspection as separate moments so you can follow the story without reading code first.

Why this route matters

The tour reveals the architectural promise of the capstone:

  • you drive the system through a readable application surface
  • the aggregate stays responsible for lifecycle and evaluation decisions
  • the runtime coordinates external concerns without owning the domain rules
  • the read models remain derived artifacts after events are emitted

Best files to read during the tour

  • src/service_monitoring/demo.py
  • src/service_monitoring/application.py
  • src/service_monitoring/runtime.py
  • src/service_monitoring/model.py
  • src/service_monitoring/read_models.py
  • COMMAND_GUIDE.md
  • WALKTHROUGH_GUIDE.md

Compare these after the tour

  • compare TOUR.md with ARCHITECTURE.md to see which scenario step maps to which boundary
  • compare TOUR.md with ARCHITECTURE.md to see how each step turns into derived state
  • compare TOUR.md with TEST_GUIDE.md to decide which executable proof best matches the story
  • compare TOUR.md with PROOF_GUIDE.md when you want to move from narrative understanding into stronger evidence