Decomposition — Example: Online Bookstore

The Starting Point

Goal: Build an online bookstore where customers can browse, search, buy books, and track orders. Administrators can manage inventory.

This is deliberately a "boring" system. It's well-understood, which lets us focus purely on the decomposition technique without domain complexity getting in the way.

Step 1: Top-Down — First Level

Ask: "What does an online bookstore need?"

Online Bookstore
├── Browsing & Search
├── Shopping Cart
├── Checkout & Payment
├── Order Management
└── Admin: Inventory

Five branches. Each is a major area of functionality. But none of these are concrete enough to build yet — "Browsing & Search" could mean a hundred different things.

Step 2: Second Level — Each Branch

Ask: "What does each of these need?"

Browsing & Search

Browsing & Search
├── List all books (paginated)
├── Search by keyword (title, author, or ISBN)
├── Filter by genre, price range, publication date
├── Sort by price / date / rating / relevance
└── View book details (description, reviews, availability)

Shopping Cart

Shopping Cart
├── Add item to cart
├── Remove item from cart
├── Update quantity
├── View cart summary (items, quantities, subtotal)
└── Cart persistence (survives page refresh, login/logout)

Checkout & Payment

Checkout & Payment
├── Enter shipping address
├── Validate shipping address
├── Select shipping method (standard, express)
├── Calculate order total (items + shipping + tax)
├── Enter payment information
├── Process payment
├── Create order record
└── Send confirmation email

Order Management

Order Management
├── View order history (list of past orders)
├── View single order details (items, shipping status, tracking)
├── Cancel order (if not yet shipped)
└── Request return (if within return window)

Admin: Inventory

Admin: Inventory
├── Add new book to catalog
├── Update book details (price, description, cover image)
├── Adjust stock levels (restock, corrections)
├── Mark book as discontinued
└── View low-stock alerts

Step 3: Check Each Leaf Against the Three Tests

For every leaf, ask:

1. Can I write a contract for it? (Inputs, outputs, errors)
2. Can I estimate the effort? (Small, medium, large)
3. Can I identify its dependencies?

Let's test a few:

"Add item to cart" — Leaf Test

Verdict: Concrete enough. This is a good leaf.

"Process payment" — Leaf Test

Verdict: Not quite decomposed enough. Let's break it down further.

Process Payment
├── Validate payment method (card not expired, sufficient funds estimate)
├── Submit payment to processor
├── Handle processor response (approved, declined, error)
├── Record payment result
└── Handle retry on transient failure

Now each sub-piece is concrete and estimable.

"Cart persistence" — Leaf Test

Verdict: This is a requirement, not a leaf. It constrains how the cart works but doesn't decompose into an operation with a contract. Move it to a "requirements" list and let it inform the design of the other cart operations.

Step 4: Dependency Map

Now draw the dependency arrows:

Book Catalog ──────────────────── (foundation — depends on nothing)
          │
          ▼
Shopping Cart ──── needs catalog for prices, stock checks
          │
          ▼
Checkout ──── needs cart contents
    │    │
    │    ▼
    │  Shipping ──── needs shipping address
    │    │
    │    ▼
    │  Order Total ──── needs cart + shipping + tax rules
    │    │
    │    ▼
    └─ Payment ──── needs order total
          │
          ▼
Order Record ──── needs payment confirmation + cart + shipping
          │
          ▼
Confirmation Email ──── needs order record

And separately:

Order Management ──── needs Order Record store (read-only)
Admin: Inventory ──── needs Book Catalog store (read-write)

What This Map Tells Us

Build order:

1. Book Catalog (no dependencies)
2. Shopping Cart (needs catalog)
3. Shipping + Tax calculations
4. Payment integration
5. Order creation
6. Email notifications
7. Order management views
8. Admin tools

Steps 3 and 4 can be built in parallel — they don't depend on each other.

Step 5: The Complete Tree

Online Bookstore
├── Book Catalog (foundation)
│   ├── Store book data (title, author, price, genre, description, cover)
│   ├── List books (paginated, sorted)
│   ├── Search books (keyword match against title/author/ISBN)
│   ├── Filter books (genre, price range, date range)
│   └── Get single book details
│
├── Shopping Cart
│   ├── Add item (book_id, quantity) → validate against catalog
│   ├── Remove item (line_item_id)
│   ├── Update quantity (line_item_id, new_quantity) → revalidate stock
│   └── Get cart summary (items, subtotal)
│
├── Checkout
│   ├── Enter shipping address
│   ├── Validate shipping address (real address? deliverable?)
│   ├── Select shipping method → calculate shipping cost
│   ├── Calculate order total (items + shipping + tax)
│   ├── Validate payment method
│   ├── Submit payment → handle response
│   ├── Record payment
│   ├── Create order record
│   └── Send confirmation email
│
├── Order Management (customer-facing)
│   ├── List my orders (paginated, newest first)
│   ├── View order details (items, status, tracking)
│   ├── Cancel order (if status = "processing")
│   └── Request return (if within 30-day window)
│
└── Admin: Inventory
    ├── Add book to catalog
    ├── Update book details
    ├── Adjust stock levels
    ├── Mark book as discontinued
    └── View low-stock alerts (books with stock < threshold)

Total leaf count: 23 operations.

Each one can be contracted, estimated, and built. The original "build an online bookstore" has been transformed from a vague idea into 23 specific, concrete tasks with a clear build order.

The Estimation Table

Rough estimate: 9 medium tasks + 18 small tasks. This is a plannable project.

What This Example Teaches

1. Start big, get specific — 5 branches became 23+ concrete leaves
2. Test every leaf — if you can't contract it, it's not done decomposing
3. Some "leaves" are actually requirements — cart persistence is a constraint, not an operation
4. Dependencies give you build order — don't guess what to build first; the map tells you
5. The boring system is a good training system — if you can fully decompose a bookstore, you can decompose anything