Application Architecture Comparison Repository

Purpose

This repository implements the same business application across multiple architectural styles.

The goal is not to declare one architecture universally best. The goal is to keep the problem space stable while changing the internal design, so the trade-offs become visible in code:

• the same business domain
• the same broad workflows
• the same canonical reference documents
• different boundaries, dependencies, and places for business logic

The repository is organized as a sequence of small, tagged lessons. Each lesson adds one architectural or workflow idea and leaves the code runnable.

Domain and Reference Documents

Most architecture tracks use the quote/order domain described by the product requirements. The canonical material is kept in docs:

• Product requirements
• Canonical domain model
• Canonical use cases
• Canonical API/CLI contract
• Domain glossary
• Architecture catalogue
• Git lesson workflow

The Blackboard Architecture track is the intentional exception: it uses the smaller Smart Invoice-to-Payment Matcher example so that the shared blackboard, knowledge sources, controller, and concurrent evaluation remain easy to see.

Implemented Architecture Tracks

The table below is the current lesson inventory. “Start” and “Latest” link to the first and final lesson currently present in each track.

Architecture	Lessons	Start	Latest
Layered	14 (001–014)	001 — skeleton	014 — conclusion
Hexagonal / Ports and Adapters	33 (001–033)	001 — skeleton	033 — conclusion
Clean	34 (000–033)	000 — transition	033 — conclusion
Onion	34 (000–033)	000 — transition	033 — conclusion
Modular Monolith	34 (000–033)	000 — transition	033 — conclusion
Microkernel / Plugin	34 (000–033)	000 — transition	033 — conclusion
Component-Based	34 (000–033)	000 — transition	033 — conclusion
Domain-Driven Design	34 (000–033)	000 — ubiquitous language	033 — conclusion
Transaction Script	34 (000–033)	000 — transition	033 — conclusion
Active Record	34 (000–033)	000 — transition	033 — conclusion
Rich Domain Model	34 (000–033)	000 — transition	033 — conclusion
Blackboard	6 (001–006)	001 — skeleton	006 — concurrent knowledge sources
Rules Engine / Knowledge-Based	34 (000–033)	000 — transition	033 — final trade-offs

The canonical ordering and the architectural summaries are maintained in docs/architectures.md.

How To Study a Track

For each architecture:

1. Read the lessons in numeric order.
2. Inspect the code introduced by the current lesson.
3. Run the tests and the demo.
4. Compare the result with the previous architecture.

Every lesson has a corresponding commit and annotated tag. Tags use the architecture slug and lesson number, for example:

git tag --list "rules-engine-*"
git switch --detach rules-engine-033

Return to the development branch when finished inspecting a tag:

git switch main

The exact commit and tag workflow is documented in docs/git-how-to.md.

Running the Examples

The architecture implementations are Go modules with tests and executable demos. From the repository root, choose a track and run:

Set-Location rules-engine-architecture
go test ./...
go run ./cmd/quote-demo

The Blackboard track has its own matcher demo:

Set-Location blackboard-architecture
go test ./...
go run ./cmd/matcher-demo

For the other tracks, replace the directory name and keep the same go test ./... / go run ./cmd/quote-demo commands.

What To Compare

As you move through the tracks, pay attention to:

• where business rules live
• which direction dependencies point
• how persistence and external systems are isolated
• how workflows are composed and tested
• how new policies, modules, plugins, or components are added
• what complexity the architecture makes easier and what complexity it introduces

The Rules Engine track returns to the canonical quote/order domain and makes facts, rules, working memory, inference cycles, derived facts, stage fulfilments, approvals, and extension points explicit. The Blackboard track focuses on opportunistic reasoning: independent knowledge sources contribute evidence to shared working memory until a match converges.

Maintaining This README

When a new architecture or lesson is added:

• update docs/architectures.md first
• add or update its row in the architecture table above
• verify the start/latest lesson links and count
• keep the demo commands and git workflow current