Architecture Quantum Analyzer

Architecture Quantum Analyzer

An architecture quantum (or "independently deployable unit") is an independently deployable artifact with high functional cohesion and synchronous connascence. The quantum count determines whether a system should use a monolith or distributed architecture — because different quanta need different quality attributes, and a single monolith can only optimize for one set.

When to Use

You're deciding whether a system should be one deployable unit or many, or you're analyzing the deployment boundaries of an existing system. Typical situations:

Before starting, verify:

Context

Required Context (must have before proceeding)

Observable Context (gather from environment if available)

Default Assumptions

Process

Step 1: Identify Components

ACTION: List all major components, services, or modules in the system.

WHY: You can't find quantum boundaries without knowing what the pieces are. Components are the building blocks — quanta are how they group based on deployment and coupling. If you're analyzing a codebase, scan the file structure. If greenfield, list the planned components.

IF codebase exists → scan directory structure, docker-compose, deployment configs ELSE → ask user to list the major components and their responsibilities

Step 2: Map Communication Patterns

ACTION: For each pair of components that communicate, determine if the communication is synchronous or asynchronous.

WHY: This is the critical step. Synchronous connascence (one component waits for another's response) means both components share fate during the call — they MUST have compatible operational characteristics. If Service A calls Service B synchronously and A needs 99.99% availability but B only has 99%, A's availability is capped at B's. Asynchronous communication (fire-and-forget via message queue) breaks this fate-sharing — each component can have independent characteristics.

Map each communication as:

Step 3: Identify Architecture Characteristics Per Component

ACTION: Determine what quality attributes each component needs. Look for differences between components.

WHY: The whole point of quantum analysis is discovering that different parts of the system need DIFFERENT characteristics. If everything needs the same scalability, reliability, and performance — it's one quantum, and a monolith is fine. But if the bidding engine needs extreme elasticity while the payment service needs extreme reliability, they're in different quanta with different architectural needs. This non-uniformity is what drives the need for distributed architecture.

CAUTION — the uniform characteristics anti-pattern: Don't assume the whole system has one set of characteristics. This is the most common mistake. Ask: "Does the order processing part of the system need the same scalability as the notification part?" If the answer is no, you have multiple quanta.

Step 4: Group Into Quanta

ACTION: Group components into quanta based on the three-criteria test. Components belong to the same quantum if they satisfy ALL THREE:

1. Deploy together — they ship as one unit (or must be deployed in lockstep) 2. High functional cohesion — they serve a unified business purpose together 3. Synchronous connascence — they communicate synchronously (fate-sharing)

WHY: These three criteria are AND conditions, not OR. Two services might deploy independently (criterion 1 fails) but communicate synchronously (criterion 3 met) — they're still NOT the same quantum because independent deployment means they CAN have different characteristics. Conversely, two components that deploy together but serve unrelated purposes (low cohesion) are forced into the same quantum by deployment, but this might be a design problem worth flagging.

Remember: Databases are part of the quantum. If two services share a database, they share a quantum — because you can't deploy the database independently from either service.

Step 5: Analyze Quantum Characteristics

ACTION: For each identified quantum, list its driving architecture characteristics (use the top 3 from architecture-characteristics-identifier). Note where quanta DIFFER.

WHY: The value of quantum analysis is revealing that different quanta have different needs. If Quantum A needs elasticity + performance and Quantum B needs reliability + security, a single monolith cannot optimize for both simultaneously. This difference is what justifies the complexity of distributed architecture.

Step 6: Determine Architecture Direction

ACTION: Based on quantum count and characteristic differences, recommend monolith vs distributed.

WHY: This is the payoff. The quantum count IS the architecture style driver:

| Quantum count | Characteristic uniformity | Recommendation | |:---:|:---:|-------------| | 1 | N/A (only one) | Monolith — single set of characteristics, simple deployment | | Multiple | Same characteristics | Monolith might still work — if quanta need the same things, a monolith can satisfy all | | Multiple | Different characteristics | Distributed required — different quanta need different optimization, monolith can't serve both |

Inputs

Outputs

Quantum Analysis Report

# Quantum Analysis: {System Name}
Components Identified
| Component | Responsibility | Deployment unit |
|-----------|---------------|----------------|
| {name} | {what it does} | {how it deploys} |
Communication Map
| From | To | Type | Mechanism | Fate-sharing? |
|------|-----|------|-----------|:---:|
| {A} | {B} | Sync/Async | REST/MQ/gRPC | Yes/No |
Quantum Map
| Quantum | Components | Driving Characteristics | Communication type |
|---------|-----------|------------------------|:---:|
| {Quantum 1} | {A, B} | {elasticity, performance} | Internal: sync |
| {Quantum 2} | {C} | {reliability, security} | External: async from Q1 |
Characteristic Comparison
| Characteristic | Quantum 1 | Quantum 2 | Quantum 3 | Uniform? |
|---------------|-----------|-----------|-----------|:---:|
| {attr} | High/Med/Low | High/Med/Low | High/Med/Low | Yes/No |
Architecture Direction
Quantum count: {N}
Characteristic uniformity: {Uniform / Non-uniform}
Recommendation: {Monolith / Distributed}
Reasoning: {why, based on quantum analysis}
Warnings
{Any anti-patterns detected: uniform characteristics assumption, shared DB coupling, etc.}

Key Principles

Examples

Scenario: Online auction system (Going Going Gone) Trigger: "Our auction platform has bidding, payment, and notification features. Should we use microservices?" Process: Identified 4 components (Bidder, Auction, Payment, Notification). Mapped communication: Bidder↔Auction is synchronous REST (same quantum — bidders need instant auction state), Auction→Payment is async via message queue (different quantum — payment needs reliability, not speed), Auction→Notification is async (different quantum — notifications can be delayed). Characteristics: Bidding quantum needs elasticity+performance (auction traffic bursts), Payment quantum needs reliability+security, Notification quantum needs availability. Three quanta with different characteristics → distributed architecture required. Output: Quantum analysis showing 3 quanta, non-uniform characteristics, recommending distributed with event-driven communication between quanta.

Scenario: Simple ordering system analysis Trigger: "We're a small team building an ordering app. Our CTO wants microservices but I think we're overcomplicating things." Process: Identified components (Order, Inventory, Payment, User). All communicate synchronously via REST, share one PostgreSQL database, deploy as one Docker container. All need the same moderate characteristics (availability, simplicity). One quantum with uniform characteristics → monolith recommended. Flagged the shared database as proof of single quantum. Output: Quantum analysis showing 1 quantum, recommending monolith. Diplomatically addressed CTO's microservices enthusiasm by showing the quantum analysis doesn't justify distribution.

Scenario: Codebase analysis of existing system Trigger: User has a codebase at ./test-env/ — "Analyze this system's architecture quanta" Process: Scanned docker-compose.yml, found 4 services with different networks. Read source files, found synchronous HTTP calls (httpx) between bidder and auction services, asynchronous RabbitMQ between auction→payment and auction→notification. Read architecture-characteristics.yaml, found different characteristic profiles per service. Grouped: Bidder+Auction (sync, shared network, same scaling) = Quantum 1, Payment (async consumer, independent) = Quantum 2, Notification (async consumer, independent) = Quantum 3. Output: Full quantum analysis with communication map, quantum groupings, characteristic comparison, and distributed architecture recommendation.

References

License

This skill is licensed under CC-BY-SA-4.0. Source: BookForge — Fundamentals of Software Architecture by Mark Richards, Neal Ford.

Related BookForge Skills

Install related skills from ClawhHub:

Or install the full book set from GitHub: bookforge-skills

Scenario: Online auction system (Going Going Gone) Trigger: "Our auction platform has bidding, payment, and notification features. Should we use microservices?" Process: Identified 4 components (Bidder, Auction, Payment, Notification). Mapped communication: Bidder↔Auction is synchronous REST (same quantum — bidders need instant auction state), Auction→Payment is async via message queue (different quantum — payment needs reliability, not speed), Auction→Notification is async (different quantum — notifications can be delayed). Characteristics: Bidding quantum needs elasticity+performance (auction traffic bursts), Payment quantum needs reliability+security, Notification quantum needs availability. Three quanta with different characteristics → distributed architecture required. Output: Quantum analysis showing 3 quanta, non-uniform characteristics, recommending distributed with event-driven communication between quanta.

Scenario: Simple ordering system analysis Trigger: "We're a small team building an ordering app. Our CTO wants microservices but I think we're overcomplicating things." Process: Identified components (Order, Inventory, Payment, User). All communicate synchronously via REST, share one PostgreSQL database, deploy as one Docker container. All need the same moderate characteristics (availability, simplicity). One quantum with uniform characteristics → monolith recommended. Flagged the shared database as proof of single quantum. Output: Quantum analysis showing 1 quantum, recommending monolith. Diplomatically addressed CTO's microservices enthusiasm by showing the quantum analysis doesn't justify distribution.

Scenario: Codebase analysis of existing system Trigger: User has a codebase at ./test-env/ — "Analyze this system's architecture quanta" Process: Scanned docker-compose.yml, found 4 services with different networks. Read source files, found synchronous HTTP calls (httpx) between bidder and auction services, asynchronous RabbitMQ between auction→payment and auction→notification. Read architecture-characteristics.yaml, found different characteristic profiles per service. Grouped: Bidder+Auction (sync, shared network, same scaling) = Quantum 1, Payment (async consumer, independent) = Quantum 2, Notification (async consumer, independent) = Quantum 3. Output: Full quantum analysis with communication map, quantum groupings, characteristic comparison, and distributed architecture recommendation.