How to Customize or Override Automatic Architectural Layer Assignments in Understand Anything

You can customize architectural layer assignments in Understand Anything by editing the LAYER_PATTERNS array in layer-detector.ts for rule-based matching, or by returning a layers array in the LLM project summary to override assignments programmatically.

Understand Anything is an open-source codebase visualization tool that automatically categorizes files into architectural layers for its knowledge graph dashboard. While the system ships with intelligent defaults, you can override these automatic assignments to align with your project's specific directory conventions or semantic structure.

How Layer Detection Works

The repository implements two complementary mechanisms in packages/core/src/analyzer/layer-detector.ts:

• Heuristic detection: Scans directory segments against the hard-coded LAYER_PATTERNS array using top-to-bottom matching. Unmatched files default to the "Core" layer.
• LLM-driven detection: Prompts the model via buildProjectSummaryPrompt in packages/core/src/analyzer/llm-analyzer.ts to return a JSON array of layers, then applies them using applyLLMLayers. Unmatched files fall into an "Other" layer.

Method 1: Customize Heuristic Pattern Matching

For projects with conventional folder naming, modify the LAYER_PATTERNS constant in packages/core/src/analyzer/layer-detector.ts. This ordered array defines which directories map to which layers.

Adding Custom Layer Patterns

Insert new entries or reorder existing ones to prioritize specific matches:

// packages/core/src/analyzer/layer-detector.ts
const LAYER_PATTERNS: Array<{
  patterns: string[];
  layerName: string;
  description: string;
}> = [
  // Existing entries...

  // Add domain-specific layer
  {
    patterns: ["domain", "biz", "business"],
    layerName: "Domain Layer",
    description: "Core domain models and business rules",
  },

  // Override API detection with more specific patterns
  {
    patterns: ["router", "routes", "api"],
    layerName: "API Layer",
    description: "HTTP route handlers and controllers",
  },
];

Critical ordering rule: Because the detector processes patterns sequentially and exits on the first match, place specific patterns (like ["router"]) before generic ones (like ["api"]) to prevent premature matching.

After modifying the array, rebuild the core package to apply changes:

pnpm --filter @understand-anything/core build

Method 2: Override with LLM-Generated Layers

For semantic detection beyond folder names, configure the LLM analyzer to return custom layer definitions in the project summary response.

Configuring the Project Summary Prompt

The function buildProjectSummaryPrompt in packages/core/src/analyzer/llm-analyzer.ts constructs the prompt sent to the language model. Ensure your LLM returns a JSON object containing a layers array with this structure:

{
  "description": "A TypeScript web service",
  "frameworks": ["Express", "Prisma"],
  "layers": [
    {
      "name": "API Layer",
      "description": "HTTP route handlers and middleware",
      "filePatterns": ["src/routes/", "src/controllers/"]
    },
    {
      "name": "Data Layer",
      "description": "Database access and models",
      "filePatterns": ["src/repositories/", "prisma/"]
    }
  ]
}

The parser parseLayerDetectionResponse handles both raw JSON and markdown-wrapped JSON (```json ... ```).

How applyLLMLayers Processes Results

When the pipeline receives the LLM response, applyLLMLayers maps file nodes to layers based on path prefixes in filePatterns. The function merges these results with any existing heuristic detections, allowing you to combine both approaches. Files not matching any LLM-supplied pattern automatically populate the "Other" layer.

Method 3: Create a Custom Layer Detector Plugin

For advanced use cases requiring external configuration files or custom logic, implement a replacement detector using the plugin system.

Register your custom analyzer in packages/core/src/plugins/registry.ts with the same signature as the default detectLayers function, then inject it into the GraphBuilder. This approach lets you read from layers.yaml, query external services, or implement regex-based matching outside the constraints of the built-in heuristic list.

Build and Deployment Checklist

Follow these steps to activate your customizations:

1. Choose your strategy: Edit LAYER_PATTERNS for folder-based rules, or modify the LLM prompt for semantic detection.
2. Implement changes: Update packages/core/src/analyzer/layer-detector.ts or adjust the prompt logic in packages/core/src/analyzer/llm-analyzer.ts.
3. Rebuild the package: Run pnpm --filter @understand-anything/core build to compile the TypeScript.
4. Regenerate the graph: Execute /understand in the target repository to see updated layer assignments in the dashboard rendered by understand-anything-plugin/src/onboard-builder.ts.

Summary

• Edit LAYER_PATTERNS in packages/core/src/analyzer/layer-detector.ts to customize folder-based heuristic detection, ordering specific patterns before generic ones.
• Provide LLM layer definitions in the project summary JSON to enable semantic file categorization via applyLLMLayers.
• Combine both methods by running heuristic detection first, then applying LLM layers for hybrid categorization.
• Register custom plugins via packages/core/src/plugins/registry.ts when you need programmatic control beyond pattern matching.

Frequently Asked Questions

Where are the default architectural layer patterns defined?

The default patterns reside in the LAYER_PATTERNS constant inside packages/core/src/analyzer/layer-detector.ts. This array contains the ordered list of directory segments that map to layers like "API," "Service," and "Data."

Can I use both heuristic and LLM-based layer detection together?

Yes. The applyLLMLayers function merges LLM-generated layers with existing heuristic assignments. Run the heuristic detector first to establish baseline categories, then call applyLLMLayers with the LLM response to refine or override specific assignments.

What happens to files that don't match any layer pattern?

Files that fail heuristic pattern matching are assigned to the default "Core" layer. When using LLM-driven detection, unmatched files are placed in an "Other" layer. You can customize these fallback behaviors by editing the default case handlers in packages/core/src/analyzer/layer-detector.ts.

How is the layer schema structured in the knowledge graph?

Layer objects are defined in packages/core/src/schema.ts and require id, name, description, and nodeIds properties. The dashboard component in understand-anything-plugin/src/onboard-builder.ts renders these layers in the onboarding view, displaying the architectural organization derived from your customized assignments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}