# Architecture metrics

Propagation cost, the cyclic core, per-service roles and a deterministic 1-10 architecture score, computed over the system graph with standard metrics.

[Conformance](https://docs.repowise.dev/multi-repo/conformance) and the cycle finder answer
*per-relationship* questions (is this edge allowed, is this loop a
cycle). Architecture metrics give the one *evaluative* read of the whole
system: how coupled it is, where its architectural core is, and a single
score you can track over time and compare across workspaces.

These are the standard MacCormack / Baldwin / Sturtevant
architecture-complexity metrics, computed deterministically over the
[system graph](https://docs.repowise.dev/multi-repo/system-map), no LLM. They use
**structural edges only** (http, grpc, event, package, db); co-change is
excluded.

When the graph has [too little evidence](https://docs.repowise.dev/multi-repo/system-map#evidence-state)
(`insufficient`), the measured figures are null and the architecture type is
`undetermined`: zero edges reads as "not seen", never as "decoupled". The
`evidence` block carries the state and its reasons.

## What it computes

- **Propagation cost**, the share of *other* services the average
  service can reach transitively through dependencies (0% = fully
  decoupled, 100% = everything reaches everything). The headline
  coupling number; lower is better.
- **Cyclic core**, the largest cyclic group of services (the largest
  strongly-connected component of the structural graph). Its size and
  ratio (core / services) describe how much of the system is tangled
  together.
- **Architecture type**, `core-periphery` when the core spans a
  meaningful fraction of the system, else `hierarchical`.
- **Per-service role**, each service classified from its visibility
  profile:
  - **Core**, in the largest cyclic group (the architectural center).
  - **Shared**, high visibility fan-in, low fan-out: many services
    depend on it, it depends on few (a widely-used utility or library).
  - **Control**, high fan-out, low fan-in: it depends on many, few
    depend on it (an orchestrator or entry point).
  - **Peripheral**, lightly coupled in both directions.
- **Architecture score**, a deterministic 1-10 roll-up (matching the
  Code Health 1-10 convention) from propagation cost, core ratio,
  dependency-cycle count, and declared-rule violation count. Lower
  coupling and a smaller core score higher.

## Using it

### CLI

`repowise workspace metrics` prints the score, propagation cost, cyclic
core, dependency-cycle count, and the per-role service breakdown.
CI-friendly plain output; `--json` emits the raw metrics.

```bash
repowise workspace metrics          # human-readable summary
repowise workspace metrics --json   # raw metrics JSON
```

### REST

`GET /api/workspace/architecture` returns the workspace metrics plus the
per-service roles. Computed at request time from the system graph (no
separate artifact); the conformance violation count, if a report exists,
is folded into the score.

### MCP

[`get_architecture`](https://docs.repowise.dev/multi-repo/workspace-mcp) gives an agent the
score, propagation cost, core members, and role breakdown in one call,
the system-structure read to consult before a cross-service refactor.

### Web

The **architecture score** appears as a stat on both the Conformance and
System Map pages. The DSM header shows score, propagation cost, and core
size, and tints each service's diagonal cell by its role, so the
on-diagonal core block stands out. On the
[System Map](https://docs.repowise.dev/multi-repo/system-map), toggle **Core** to
highlight the cyclic core, and the inspector shows any selected service's
role and visibility profile.

> **Note**
>
> The score is deterministic and uses only structural edges, so it moves
> when the dependency topology changes, not when commit activity does.
> That makes it a stable number to track release over release.