Diagnosing and Fixing Architectural Drift in Sema

The Problem: Architectural Drift

Architectural drift occurs when the actual implementation of a codebase deviates from its intended design. In Sema (v2.x), this manifests as a spike in "Architecture Violations" on the dashboard, often appearing after large merges to the main branch. If left unchecked, drift leads to "spaghetti code" where layers are bypassed and dependencies become circular, making the system fragile and difficult to refactor.

Identifying the Drift

You can recognize architectural drift through three primary indicators in the Sema dashboard:

• Forbidden Dependency Alerts: Notifications that a package is importing a module it is explicitly restricted from accessing.
• Layer Breach Warnings: Alerts indicating a call graph edge exists between non-adjacent layers (e.g., the Presentation layer calling the Data layer directly).
• Rising Risk Score: A delta of >15 points in the weekly Risk Score, signaling a systemic degradation of structural integrity.

Diagnostic Mapping

Use the following table to map the Sema violation type to the likely root cause.

Violation Type	Common Root Cause	Diagnostic Signal
Forbidden Dependency	Direct import of internal implementation packages.	New import statement in a PR targeting a restricted namespace.
Layer Breach	Missing facade or service layer.	Call graph edge skipping a mandatory architectural tier.
Cyclic Dependency	Refactoring introduced a back-reference.	Mutual imports between two or more modules.
Unowned Code	New module lacks assignment.	Files appearing without a team label in the Architecture view.

Step-by-Step Diagnostic Process

1. Isolate the Change: Open the violating Pull Request in the Sema PR view. Identify the specific commit that triggered the alert.
2. Analyze the Call Graph: Click the violation alert to open the call-graph snippet. Trace the path from the caller to the callee to see exactly where the boundary was crossed.
3. Validate Rule Intent: Inspect .sema/architecture.yaml in the repository root. Ensure the rule is still valid for the current project goals and not a legacy constraint.
4. Local Reproduction: Run the analysis locally to confirm the UI is not reporting a stale state. Run this from the repository root:

   # Requires Sema CLI installed and authenticated
   sema analyze --local

   Risk: Running this on very large monorepos may consume significant local memory.
5. Check Ownership: If the violation is "Unowned Code," check .sema/ownership.yaml to see if the new directory was omitted.

Remediation Strategies

Apply the fix based on the diagnostic finding:

• For Forbidden Dependencies: Replace the direct import with a call to a public API. If the import is strictly necessary for a temporary migration, add an allowed exception in architecture.yaml with a defined expiry date.
• For Layer Breaches: Introduce an interface or service layer to encapsulate the logic. Update the callers to use the new service and add an integration test to verify the boundary.
• For Cyclic Dependencies: Break the cycle using dependency inversion (introducing an interface) or an event bus. Document this change in an Architecture Decision Record (ADR).
• For Unowned Code: Assign the owning team in ownership.yaml and propagate the change using the CLI:

  # Run from repo root with write permissions to .sema/ folder
  sema ownership sync

  Note: UI edits to ownership do not automatically propagate to the analyzers; the CLI sync is required.

Limitations and False Positives

Sema may flag generated code (such as gRPC or GraphQL stubs) as violations because they often bypass standard layering. To prevent this, add the generated paths to .sema/ignore.yaml. Additionally, be aware that self-hosted instances may have a rule-engine version lagging behind the SaaS version by 2-4 weeks; verify your version in Admin → System Info.

Verification of Fix

To verify the resolution, run the following command locally to generate a JSON report of remaining violations:

sema analyze --format=json --output=violations.json

Compare the count in violations.json against the Sema dashboard. The fix is successful when the local count matches the UI and the PR check passes.

Escalation Criteria

Escalate the issue to the Architecture Review Board (ARB) if any of the following occur:

• More than 5 new violations are introduced in a single PR.
• Violations persist for more than 3 consecutive sprints.
• The drift occurs within a critical-path service (e.g., Authentication or Payments).
• The weekly Risk Score delta exceeds 15 points.

When escalating, provide a CSV export of the violations and a proposed ADR for the structural change.