Tutorial: Architecture Design

Verify you're ready

This tutorial builds on the discuss output from Tutorial 6. Before starting, cd into your tutorial project and confirm:

• docs/feature/<feature-id>/discuss/user-stories.md
• docs/feature/<feature-id>/discuss/journey-core.yaml (or journey-core-visual.md)

If either is missing, complete Tutorial 6: Requirements and UX Journey first.

What You'll Build

A complete architecture package for the bookmark CLI -- component boundaries, technology decisions, and visual diagrams.

Before: You have validated requirements from Tutorial 6 (user stories, acceptance criteria, UX journey) in docs/feature/bookmark-cli/discuss/. But you have no architecture, no technology decisions, and no component design.

After: You have an architecture document defining how the bookmark CLI is structured (domain layer, CLI adapter, storage adapter), ADRs explaining each technology choice, and Mermaid diagrams you can render in any markdown viewer. Architecture lives in docs/product/architecture/ (SSOT) with feature-specific deltas in docs/feature/bookmark-cli/design/.

Why this matters: Jumping from requirements to code skips the question "how should the pieces fit together?" /nw-design answers that question with documented decisions and visual diagrams, so the DISTILL and DELIVER waves have clear boundaries to work within.

Step 1 of 9: Confirm Your Starting Point (~1 minute)

You should be in the bookmark-cli project from Tutorial 6, with requirements artifacts committed.

Verify:

ls docs/feature/bookmark-cli/discuss/user-stories.md

You should see:

docs/feature/bookmark-cli/discuss/user-stories.md

Check that your requirements include user stories:

head -5 docs/feature/bookmark-cli/discuss/user-stories.md

You should see the beginning of your user stories file from Tutorial 6 (content varies based on your discuss session).

If docs/feature/bookmark-cli/discuss/ does not exist: Complete Tutorial 6 first. This tutorial builds directly on its output.

Next: you will launch the design command and answer architecture questions.

Step 2 of 9: Launch the Design Session (~2 minutes)

Open Claude Code if it is not already running:

claude

Start the architecture design:

/nw-design bookmark-cli

AI output varies between runs. Your conversation with the architect will differ from the examples below. That is expected -- the architect adapts to your requirements and codebase. What matters is the structure (decisions, architecture document, diagrams), not the exact wording.

/nw-design starts with two routing decisions before design begins:

Decision 1: Design scope -- What are you designing?

For a CLI tool like bookmark-cli, pick Application / components. This routes to Morgan.

Decision 2: Interaction mode -- How do you want to work?

Pick Guide me for this tutorial so you can see the decision process.

After these two routing decisions, Morgan asks four architecture decisions. Give these answers:

What just happened? /nw-design routed you to Morgan (application scope) in guided mode. Morgan then asked four foundational architecture decisions. For a CLI tool, the simplest options (hexagonal monolith, synchronous, single database) are the right choices.

Next: Morgan will analyze your codebase and design the architecture.

Step 3 of 9: Watch the Design Process (~3 minutes)

After your answers, Morgan works through several phases. You will see them scroll by as a continuous flow:

Searching existing codebase for related functionality...
  Glob: **/*.py -- found 0 existing modules
  Grep: "bookmark" -- no existing implementations
Existing system analysis: greenfield project, no reuse opportunities.

Designing component architecture...
  Creating docs/feature/bookmark-cli/design/architecture-design.md
  Creating docs/feature/bookmark-cli/design/component-boundaries.md
  Creating docs/feature/bookmark-cli/design/technology-stack.md

Writing Architecture Decision Records...
  Creating docs/adrs/ADR-001-hexagonal-architecture.md
  Creating docs/adrs/ADR-002-sqlite-storage.md
  Creating docs/adrs/ADR-003-click-cli-framework.md

Invoking peer review (Atlas)...
Review result: APPROVED
- Component boundaries: clear separation
- Technology choices: justified with alternatives
- ADR quality: meets MADR template

The design process has four phases: codebase analysis (check what exists), architecture design (write the documents), ADR creation (record each decision), and peer review (automated quality check). You do not need to intervene -- just watch them complete.

If the reviewer finds issues: Morgan fixes them automatically. This may take 1-2 iterations. You do not need to intervene unless Morgan asks a question.

ls docs/feature/bookmark-cli/design/

architecture-design.md
component-boundaries.md
technology-stack.md
data-models.md

Step 4 of 9: Understand the Hexagonal Architecture (~2 minutes)

Check what Morgan created:

ls docs/feature/bookmark-cli/design/

You should see:

architecture-design.md
component-boundaries.md
technology-stack.md
data-models.md

Your file names may differ slightly. Morgan names files based on your specific design. The pattern docs/feature/{name}/design/*.md is what matters.

Look at the component boundaries:

head -40 docs/feature/bookmark-cli/design/component-boundaries.md

You will see something like:

# Component Boundaries

## Domain Layer (bookmark_cli.domain)
- Bookmark entity: URL, title, tags, created_at
- SearchService: keyword matching across URLs, tags, titles
- TagManager: tag normalization and validation

## Port Interfaces (bookmark_cli.ports)
- BookmarkRepository (driven port): save, find_by_id, search
- CLIPresenter (driving port): format output for terminal

## Adapters (bookmark_cli.adapters)
- SQLiteRepository implements BookmarkRepository
- ClickCLI implements CLIPresenter

What just happened? Morgan designed a hexagonal architecture with three layers. The domain holds your business logic (bookmarks, search, tags) with zero knowledge of storage or CLI frameworks. Ports are interfaces the domain exposes or depends on. Adapters are concrete implementations (SQLite, Click) that plug into those ports. This means you can swap storage or CLI framework without changing domain logic.

Next: you will explore the decision records that justify each technology choice.

Step 5 of 9: Explore the Decision Records (~1 minute)

Check the ADRs:

ls docs/adrs/

You should see 2-4 ADR files. Open one:

head -30 docs/adrs/ADR-001-hexagonal-architecture.md

Each ADR follows a standard template: Status, Context, Decision, Alternatives Considered, Consequences. This is your decision record -- if someone asks "why hexagonal?" six months from now, the answer is documented.

If docs/adrs/ does not exist: Morgan may have placed ADRs inside docs/feature/bookmark-cli/design/. Check there instead.

Next: you will generate visual architecture diagrams.

Step 6 of 9: Generate Architecture Diagrams (~2 minutes)

With the architecture defined, generate visual diagrams:

/nw-diagram bookmark-cli --format=mermaid --level=container

Morgan reads the architecture documents and produces Mermaid diagrams. You will see:

Generating diagrams from architecture documents...
  Creating docs/feature/bookmark-cli/design/diagrams/system-context.md
  Creating docs/feature/bookmark-cli/design/diagrams/component-architecture.md

Your file names and count may differ. Morgan generates diagrams based on the complexity of your architecture. A simple CLI tool typically gets 2-3 diagrams.

Open the component diagram:

cat docs/feature/bookmark-cli/design/diagrams/component-architecture.md

You will see a Mermaid code block like:

```mermaid
graph TD
    User([Developer]) -->|CLI commands| CLI[Click CLI Adapter]
    CLI --> Domain[Domain Layer]
    Domain --> |BookmarkRepository port| SQLite[SQLite Adapter]
    SQLite --> DB[(bookmarks.db)]

    subgraph "bookmark-cli"
        CLI
        Domain
        SQLite
    end
```

Copy only the lines between the triple backticks (the graph TD block), not the surrounding markdown fencing. The ```mermaid and ``` lines are markdown syntax that tells renderers to treat the content as a diagram -- they are not part of the diagram itself.

Your diagram will differ. Morgan generates diagrams from your specific architecture. The structure (user, adapters, domain, storage) is what matters, not exact node names.

To render the diagram, paste the Mermaid block into any Mermaid-compatible viewer:

• GitHub: Mermaid renders automatically in .md files
• VS Code: Install the "Mermaid Preview" extension
• Online: Paste at mermaid.live

What just happened? /nw-diagram read the architecture documents from the design phase and produced visual representations. The diagrams follow the C4 model: context (who uses the system), container (major components), and component (internal structure). You chose the container level, which shows how the CLI, domain, and storage relate.

If you see "No architecture documents found": Make sure Step 3 completed successfully. Run /nw-design bookmark-cli again if needed -- Morgan will pick up where it left off.

Next: you will review all artifacts and commit them.

Step 7 of 9: Review and Commit Artifacts (~2 minutes)

Check the full artifact tree:

find docs/feature/bookmark-cli/design docs/adrs -type f 2>/dev/null | sort

You should see something like:

docs/adrs/ADR-001-hexagonal-architecture.md
docs/adrs/ADR-002-sqlite-storage.md
docs/adrs/ADR-003-click-cli-framework.md
docs/feature/bookmark-cli/design/architecture-design.md
docs/feature/bookmark-cli/design/component-boundaries.md
docs/feature/bookmark-cli/design/data-models.md
docs/feature/bookmark-cli/design/technology-stack.md
docs/feature/bookmark-cli/design/wave-decisions.md

Your file list will differ. Count matters more than exact names. You should have: 1 architecture document, 1 component boundaries file, 1 technology stack file, 2+ ADRs, and 1+ diagrams.

Commit everything:

git add -A && git commit -m "docs: architecture design and diagrams from design session"

You should see:

[main ...] docs: architecture design and diagrams from design session

Next: a recap of what you built and where it feeds into the next wave.

Step 8 of 9: What You Built (~1 minute)

You started with requirements and ended with a complete architecture package:

1. Architecture and component boundaries -- How the bookmark CLI is structured (domain, ports, adapters) with clear responsibilities for each layer
2. Technology decisions (ADRs) -- Decision records for architecture style, storage, and CLI framework, each with alternatives considered
3. Visual diagrams -- Mermaid diagrams showing system context and component architecture

Step 9 of 9: The Wave So Far (~30 seconds)

DISCOVER             DIVERGE              DISCUSS              DESIGN               DISTILL
(/nw-discover)       (/nw-diverge)        (/nw-discuss)        (/nw-design)         (/nw-distill)
────────────────     ────────────────     ────────────────     ────────────────     ────────────────
"Is the problem      "Which direction     "What should we      "How should we       "Generate test
 real?"               should we go?"       build?"              build it?"           specs"

Evidence-based       Design exploration   Journey + stories    Architecture +       Acceptance tests
validation           + recommendation     + acceptance         ADRs + diagrams      from requirements
                     (optional)           criteria                                  + architecture

Tutorial 4           Tutorial 5           Tutorial 6           This tutorial        Tutorial 8

Each wave builds on the previous one. The architecture document references your user stories. The component boundaries map to your acceptance criteria. Nothing is designed in a vacuum.

Next Steps

• Tutorial 8: Generating Acceptance Tests -- Take your architecture into /nw-distill to auto-generate BDD acceptance tests from user stories and component boundaries
• Read an ADR aloud -- If the "Alternatives Considered" section explains why each was rejected, the ADR is well-written. If it just lists names without rationale, it needs more detail.
• Render a diagram -- Paste the Mermaid code into mermaid.live and see the visual architecture. Share it with a teammate to validate the design.

Troubleshooting

Last Updated: 2026-04-06