Skip to main content

Scenario 11: Architecture analysis

Use this scenario to investigate dependencies, cycles, layer violations, coupling, or structural risk inside one project.

User Guides

Use this scenario to investigate dependencies, cycles, layer violations, coupling, or structural risk inside one project. It converts a review question into source-bound dependency evidence; the architecture decision record and accountable reviewer use that evidence to record the decision.

When to use it

Good questions name a bounded component and a decision:

  • Which modules depend on the payment adapter?
  • Does this change introduce a dependency cycle?
  • Which layer violations are relevant to the proposed boundary?
  • What is the blast radius of extracting a component?

Use Scenario 10 when several repositories are in scope, and Scenario 09 for a revision-level code review.

Prerequisites and scope

Open an accepted review task, bind it to the project revision, and limit file_paths to the component under review. The project CPG must represent that revision. If the CPG is stale, refresh it before interpreting the result.

Do not copy implementation thresholds from source into a decision record. Handler priorities, query limits, and heuristics are implementation details and may change without altering this user contract.

Architecture projection in the CPG

The CPG keeps its syntax, symbol, call, and data-flow facts and adds a revision-bound architecture projection above them. A component has a stable component UID, a readable ID, and an optional parent UID. Renaming a component therefore does not erase its identity or its place in the hierarchy.

For a complete run, every in-scope file or symbol belongs to exactly one component. Gaps, conflicting selectors, and selectors that match nothing are explicit diagnostics; they are not silently treated as successful coverage. Each dependency fact records its type, source set, source and target language, and whether the evidence is direct or transitive. Transitive evidence preserves its path so that a reviewer can reproduce the conclusion.

The language capability manifests for C, C++, JavaScript, and TypeScript are independent. Support or limitations for one language do not imply the same result for a neighboring language.

This foundation makes the model deterministic and inspectable. Rule enforcement, contract management, release gates, adoption checks, and ready-made presets belong to separate delivery stories. Scenario 11 supplies the architecture projection used by those controls.

Run the typed scenario

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Find dependency cycles and layer violations around the payment adapter.",
    employee_id="codegraph_reviewer",
    scenario_id="scenario_11",
    event_type="review_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["<revision-ref>", "<architecture-rule-ref>"],
        "file_paths": ["<bounded-source-path>"],
    },
)
result = invoke_role_bound_scenario_request(request)

Use one question per run. A narrow query produces evidence that is easier to reproduce and review than a generic request to “analyze the architecture.”

Read the result

Preserve:

  • answer for the synthesized explanation;
  • evidence and cpg_results for dependency evidence and supporting locations;
  • metadata.role_bound_scenario_invocation for the reviewer, event, workflow, and preflight status;
  • the revision and architecture rule referenced by the task.

Check every decision-relevant path in the source revision. Absence of a finding may mean the query, CPG coverage, or configured rule set did not cover the intended boundary.

Safety and authority boundaries

Scenario 11 analyzes the project and returns recommendations. It is not an architecture approval. The accountable architecture owner accepts deviations, updates the ADR, approves a merge, and confirms runtime conformance using this evidence.

An accountable architecture review must state the decision, alternatives, accepted risks, affected owners, tests, and rollback conditions. Product acceptance and release authorization remain separate evidence lanes.

Failure and recovery

  • Empty result: verify the exact component name, revision, CPG freshness, and rule coverage.
  • Handler fallback: mark the answer as a hypothesis and retain the error or fallback signal.
  • Conflicting runs: compare revision, scope, and rules before comparing findings.
  • Suspected runtime-only dependency: supplement static analysis with runtime or deployment evidence.

Source contract

This guide is bound to:

  • src/workflow/scenarios/architecture_core/architecture.py — architecture workflow and evidence;
  • src/workflow/scenarios/architecture_handlers/workflow.py — specialized dependency handlers;
  • src/digital_employees/runtime/scenarios/role_bound_scenario_invoker.py — typed routing;
  • src/digital_employees/runtime/scenarios/employee_scenario_invocation.py — reviewer ownership and required event.
  • gocpg/pkg/architecture — component classification, typed dependency graph, and language capability manifests;
  • gocpg/pkg/storage/duckdb/schema.go — run-scoped architecture projection storage.
Report a documentation issue