Brewbuddy Diagrams — Documentation skill for Claude Code

BrewBuddy

BrewBuddy is a small fictional cafe ordering system. A customer places an order for one or more menu items and pays for it. If the payment matches the order total, the cafe prepares the order, marks it ready, and hands it over. If the payment does not match, the order is cancelled.

It is a reference project for learning Mermaid diagrams. The code exists to be diagrammed, so it is deliberately small and readable, and it favours clarity over completeness. There is no running server and no database.

Diagrams

See [ARCHITECTURE.md](ARCHITECTURE.md) for the full write up, which embeds five Mermaid diagrams that GitHub renders inline:

• a flowchart of the order placement and payment workflow
• a sequence diagram of the request path through the layers
• an entity relationship diagram of the data model
• a class diagram of the code structure
• a state diagram of the order lifecycle

Each one is also kept as its own file in [diagrams/](diagrams).

Files

models.py       Domain classes: Customer, MenuItem, OrderItem, Order, Payment.
repository.py   In memory store standing in for a database.
service.py      Business logic and every order status change.
api.py          Thin Flask style route functions calling into service.py.
diagrams/       One .mmd file per diagram.
ARCHITECTURE.md The diagrams with explanation.

Trying it out

There is nothing to install and nothing to start. The route functions in `api.py` are plain functions that take a request body and return a `(body, status_code)` pair, so you can drive the whole workflow from a Python prompt:

import models, repository, api

repository.add_customer(models.Customer(1, "Ada", "ada@example.com"))
repository.add_menu_item(models.MenuItem(1, "Flat White", 3.5))

api.place_order({"customer_id": 1, "items": {"1": 2}})
api.take_payment(1, {"amount": 7.0})
api.mark_preparing(1)
api.mark_ready(1)
api.collect_order(1)

How this was built

The code was written first, then the five