Capstone Architecture and Project Skeleton

Capstone Architecture and Project Skeleton

The capstone reads line-oriented events, validates records, filters levels, computes summaries, and emits text or JSON. Its architecture keeps parsing and aggregation pure while adapters own files, arguments, and output.

Module: Module 7: Capstone: A Tested Log Reporting CLI

Core mental model

This lesson is built around four connected ideas. Read them as a decision framework, then prove each one with the walkthrough.

• cli depends on parser and report, never the reverse.
• The record grammar and failure policy should be written before implementation.
• Rendering and aggregation remain separate so formats share one summary model.
• One vertical slice should work before every feature is attempted.

Walkthrough

logreport/
  __init__.py
  cli.py
  models.py
  parser.py
  report.py
tests/
  test_cli.py
  test_parser.py
  test_report.py
pyproject.toml
README.md

models owns Event and Summary, parser turns lines into events, report aggregates and renders, and cli coordinates options, paths, logging, and exit status.

Hands-on lab

Create the skeleton and one working slice in which one input line produces one text summary. Document every dependency edge and the input grammar.

What to watch for

• Starting every feature at once makes failures too broad.
• Letting the parser print couples domain logic to a terminal.
• An undocumented grammar makes validation rules look arbitrary.

Engineering checklist

• Connect the lesson's mental model to the choices made in the walkthrough.
• Test the normal case, an empty or boundary case, and one invalid case.
• Keep external input, side effects, and reusable logic in clearly separated layers.
• Prefer the clearest correct implementation before optimizing or generalizing it.

Completion check

You can implement the lab without copying the example, explain the core concepts in your own words, and show tests or terminal output that demonstrate the expected and failure paths.