Brick architecture review reference

Use this reference when interpreting a Brick artifact, comparing two artifacts, or proposing a structural gate. The graph is evidence; the architectural conclusion still requires source inspection.

Canonical graph vocabulary

The schema-v4 artifact contains schema_version, generated_by, root, scope, nodes, edges, metrics, and diagnostics. Structural health is nested at metrics.structural_health; exact P4 structural observations are nested at metrics.p4.

Node kinds:

repository
directory
file
class
function
external
finding

Edge kinds:

contains
defines
calls
imports
inherits
flags

Each edge's ordered evidence array retains lane, backend, confidence, and provenance records explaining how the relationship was produced. Preserve all records when filtering or transforming data. Confidence labels from different backends are not interchangeable probabilities. P4 consumers must also retain node p4.kind and edge p4.relation attributes; coarse class/function/calls kinds are display categories, not complete P4 semantics.

Current health model

Brick's aggregate health score is an experimental weighted summary:

Component	Weight	Observable property
Acyclicity	35	Share of dependency structure outside cyclic components
Resolution	25	Share of dependency targets resolved inside the repository
Connectedness	25	Share of modeled nodes participating in relationships
Concentration	15	Degree concentration rather than architectural intent

Always report the component values and relevant raw counts. Do not compare aggregate scores when language mix, ignored paths, Brick version, parser coverage, or scan scope differs materially. For P4, report parser/apply SCCs, unreachable states, and unresolved dependencies from metrics.p4; do not relabel them as compiler or verifier results.

Review sequence

Inspect diagnostics and tool/schema versions.
Confirm expected files and languages appear in the node inventory.
Count node kinds, edge kinds, evidence lanes, and confidence labels.
Inspect cyclic strongly connected components, including self-loops.
Rank dependency fan-in and fan-out for calls, imports, and inheritance.
Review external targets and determine which are expected ecosystem boundaries.
If Fold findings exist, locate findings attached to hubs or cycles while preserving Fold provenance.
Open the source for every material conclusion.

Useful queries

Basic inventory:

jq '{schema_version, generated_by, root, diagnostics, metrics,
     node_kinds: (.nodes | group_by(.kind) | map({kind: .[0].kind, count: length})),
     edge_kinds: (.edges | group_by(.kind) | map({kind: .[0].kind, count: length}))}' \
  build/brick/architecture.json

Evidence inventory:

jq '[.edges[] | .evidence[]? |
      {lane: (.lane // "unknown"),
       backend: (.backend // "unknown"),
       confidence: (.confidence // "unknown")}] |
    sort_by([.lane, .backend, .confidence]) |
    group_by([.lane, .backend, .confidence]) |
    map({lane: .[0].lane, backend: .[0].backend,
         confidence: .[0].confidence, count: length})' \
  build/brick/architecture.json

Fold findings with their Flags evidence:

jq '[. as $graph | $graph.nodes[] | select(.kind == "finding") as $finding |
     {id: $finding.id, name: $finding.name, attributes: $finding.attributes,
      flags: [$graph.edges[] |
              select(.kind == "flags" and .source == $finding.id) |
              {id, attributes, evidence}]}]' build/brick/architecture.json

Prefer the bundled architecture_summary.py helper for cycle and hub computation because it applies the same deterministic dependency-edge filter on every run.

For MCP-aware clients, brick mcp architecture.json provides four read-only queries over the same artifact: dependency/dependent impact, canonical SCCs, weak-undirected dependency bridges, and complete node/edge evidence lookup. Require query schema version 1 and building schema version 4, retain complete records, and verify material results in source. The MCP server is a consumer, not an additional analyzer.

Baseline comparison

Keep both raw artifacts. Compare them only after checking schema version, repository identity, scan scope, tool version, languages, diagnostics, and total file/symbol coverage. Schema v4 rejects different absolute root paths, repository identities, exclusions, or P4 frontends by default; cross-worktree comparison needs a future explicit repository identity override rather than an inferred match.

For compatible models, use Brick's versioned stable-ID diff rather than ad hoc set subtraction:

brick check after.json --min-score 0 --baseline before.json \
  --diff-json build/brick/structural-diff.json

The diff retains complete added/removed records and before/after records for shared IDs whose node fields, edge attributes, or evidence changed. Treat removals/additions as leads: renames and parser changes can resemble architectural churn. Add explicit --max-{added,removed,changed}-{nodes,edges} only when the project has adopted those absolute-count gates.

For project-owned forbidden dependency boundaries, use a versioned policy and retain the complete result:

brick check after.json --min-score 0 \
  --policy architecture-policy.json \
  --policy-result-json build/brick/policy-result.json

Reject scope mismatches and unknown policy keys/kinds instead of adapting them. Use each matched edge's original evidence and provenance when verifying a violation in source.

Findings template

For each verified issue record:

Finding: concise statement of the structural risk.
Scope: affected files, classes, functions, and graph IDs.
Evidence: Brick edges and their provenance plus direct source observations.
Impact: the repository-specific consequence.
Confidence: concrete, inferred, or exploratory, with coverage limitations.
Action: smallest defensible refactor, test, documentation change, or follow-up analysis.

Conclude with artifact locations and a coverage statement. Avoid architecture grades such as good, clean, or safe unless the project has supplied an explicit rubric and the evidence satisfies it.

6.2 KiB Raw Permalink Blame History