Skip to main content

Scenario 11: Architecture analysis

Find dependencies, cycles and layer violations in one project, assess affected components and prepare a source-backed architecture decision.

User Guides

Use this scenario to investigate dependencies, cycles, layer violations, coupling, or structural risk inside one project. It connects an architecture question to dependencies and source locations. The reviewer uses the result to choose component boundaries and explain the architecture 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. Follow the CPG audit guide to prepare the project and check the graph.

Prepare the Python environment and configuration using the CLI guide and programmatic guide. Confirm that the required graph services are reachable and configure the LLM for workflow paths that use it. At invocation, CodeGraph checks the reviewer role, task and scenario readiness.

Architecture projection in the CPG

The architecture model groups CPG files and symbols into components, such as the web layer, services, and storage. It defines component nesting and links dependencies to the reviewed revision. A stable component identifier lets you compare results after changing its name.

Model rules select files and symbols for each component. The report shows classification coverage, objects without a component, and objects assigned to multiple components. The model policy sets the required coverage and how these results are handled. For example, full coverage requires a component for every in-scope object; if code in src/payments/** matches no component selection rule, the report exposes that gap. Building the dependency graph requires each participating object to belong to one component. 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.

For C, C++, JavaScript, and TypeScript, the language profile defines the available dependency types. Rule validation compares the required dependencies with that profile. For example, a forbidden-import rule uses import facts and file-to-component membership.

For a release check, select a control profile, define the rules, and set the component scope. The check uses projection completeness and coverage of that scope. See Architecture control in CodeGraph for the model, DSL, contracts, presets, and safe adoption sequence.

Run the typed scenario

Save the example as a Python file in the CodeGraph checkout. Activate the environment with the project dependencies installed and run the file from the repository root. Replace the project, namespace, task, evidence-reference and path placeholders with the accepted scope. Adapt the question to the component you actually review.

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)
if result.get("error"):
    raise RuntimeError(result["error"])
if not result.get("scenario_id") or not result.get("answer"):
    raise RuntimeError("Scenario returned no scenario identity or answer")
print(result["answer"])

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.

Match each decision-relevant path to the source revision and selected rule. Use this comparison to identify dependencies to change and tests to repeat.

For example, you are extracting a payment adapter and want to preserve the boundary between the web layer and storage. Ask about calls from the web layer, then compare the resulting paths with the allowed sequence: web layer → service → storage. A direct call from the web layer to storage becomes a review item: move the call into the service or record a justified deviation in the ADR. This illustrates how to frame the question; analysis of your project supplies the actual paths.

In metadata.architecture_adoption, source identifies the result source, canonical indicates use of a canonical run, and gate_eligible describes eligibility for a release check. A canonical result binds findings to a project, commit and rules. Compare project_key and commit_hash with the reviewed project and revision, and model_hash and rules_hash with the selected model and rules. Preserve run_id to link the conclusion to the specific run. Discovery results help select review questions. If the answer says architecture control is not configured, prepare the model and rules, then run the scenario again.

Record the architecture decision

Scenario 11 gathers analysis results for architecture review. The architecture owner uses them to select a change, accept deviations and update the architecture decision record (ADR). Preserve the reviewed revision, findings and links to the corresponding source locations.

Record the decision, alternatives, accepted risks, owners, tests and rollback conditions in the ADR. After implementation, check the changed revision and compare the result with the selected component boundaries.

Use the project delivery process for architecture changes; this scenario supplies evidence for their review.

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.
Report a documentation issue