Architectural tradeoffs tutorial

This tutorial shows architecture as runtime behavior. You will compare scenarios where service granularity, event semantics, placement rules, and orchestration choices either preserve or degrade coherence.

By Enrico Piovesan Updated June 22, 2026

Tutorial route

Keep the chapter sequence in view so the comparison path stays obvious while you read the tradeoff scenarios.

Open source folder All UMA examples Previous: Trust Boundaries Next: Evolution Without Fragmentation

What you will learn

why more services are not automatically better architecture
how metadata works as a control plane
how clearer constraints recover coherence after ambiguity or over-orchestration

Prerequisites

Rust 1.76 or newer
Node.js 20 or newer
a checkout of the repository

Full tutorial

Enter the example
```
cd chapter-10-architectural-tradeoffs
```
List the architecture labs
```
./scripts/list_labs.sh
```

Validate the baseline

./scripts/validate_architecture.sh lab1-baseline

Run the coherent baseline

./scripts/run_arch_demo.sh lab1-baseline

Compare over-granular decomposition

./scripts/diff_architecture.sh lab1-baseline lab2-over-granular

Run the runtime ambiguity lab

./scripts/run_arch_demo.sh lab4-runtime-ambiguity

Run the recovered architecture lab

./scripts/run_arch_demo.sh lab6-recovered-architecture

Run the full smoke path
```
./scripts/smoke_arch_labs.sh
```

What to inspect

After each command, look for these proof points. They are the signals that connect the code example back to the UMA architecture claim.

Verdict
architectural decision axes
over_granular
hidden_event_coupling
runtime_ambiguity
over_orchestrated

Acceptance check

The chapter-level validation path is:

./scripts/smoke_arch_labs.sh

Return to the repository root for the final acceptance gate:

cd ..
./scripts/smoke_reader_paths.sh

Where to go next

Chapter 11 focuses on evolution without fragmentation.

Open source folder All UMA examples Read Chapter 11: Patterns and Tradeoffs → Previous: Trust Boundaries Next: Evolution Without Fragmentation