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

> Customize architectural layer assignments in Understand Anything by editing LAYER_PATTERNS or programmatically overriding with LLM project summaries. Gain control over your code's layers.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-05-31

---

**You can customize architectural layer assignments in Understand Anything by editing the `LAYER_PATTERNS` array in [`layer-detector.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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:

```typescript
// 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:

```bash
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`](https://github.com/Lum1104/Understand-Anything/blob/main/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:

```json
{
  "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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/analyzer/layer-detector.ts) or adjust the prompt logic in [`packages/core/src/analyzer/llm-analyzer.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/onboard-builder.ts).

## Summary

- **Edit `LAYER_PATTERNS`** in [`packages/core/src/analyzer/layer-detector.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts) and require `id`, `name`, `description`, and `nodeIds` properties. The dashboard component in [`understand-anything-plugin/src/onboard-builder.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/onboard-builder.ts) renders these layers in the onboarding view, displaying the architectural organization derived from your customized assignments.