# How the Understand-Anything Architecture-Analyzer Identifies API, Service, Data, UI, and Utility Layers

> Understand-Anything's architecture-analyzer automatically identifies API, Service, Data, UI, and Utility layers using heuristics and LLMs. Classify your codebase effortlessly.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: architecture
- Published: 2026-06-18

---

**The architecture-analyzer in Understand-Anything uses a two-step hybrid approach that combines fast heuristic pattern matching against directory names with an LLM-driven refinement fallback to automatically classify files into API, Service, Data, UI, Utility, and other architectural layers.**

The Understand-Anything architecture-analyzer automatically maps source files to high-level architectural layers without manual configuration. By analyzing file paths and directory structures, it categorizes code into logical tiers using a hybrid detection strategy implemented in the [`layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layer-detector.ts) module.

## Heuristic Detection via Directory Pattern Matching

The first phase employs **heuristic detection**, a rule-based pass that matches file paths against predefined directory-name patterns. This approach provides fast, deterministic classification without external API calls.

### The LAYER_PATTERNS Constant

At the core of this logic resides the `LAYER_PATTERNS` constant defined in [`layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layer-detector.ts). This constant maps directory-name patterns to their corresponding architectural layers. For example, directories named `routes`, `controllers`, or `api` map to the **"API Layer"**, while `services`, `business`, or `logic` directories map to the **"Service Layer"**.

### The matchFileToLayer Function

The `matchFileToLayer(filePath)` function (lines 85-94) normalizes the input path, splits it into segments, and returns the first matching layer name. It iterates through path segments against the `LAYER_PATTERNS` dictionary, ensuring immediate classification based on directory conventions.

### The detectLayers Function

The `detectLayers(graph)` function iterates over every **file** node in the **knowledge graph**, invoking `matchFileToLayer` for each node. It groups node IDs under their resolved layer names, producing an array of `Layer` objects. Files that fail to match any pattern are automatically assigned to a fallback **Core** layer, ensuring complete graph coverage.

## LLM-Driven Refinement for Ambiguous Files

When the heuristic pass cannot confidently resolve a layer, the analyzer falls back to a **language-model prompt** that analyzes the entire codebase context.

### Building the Layer Detection Prompt

The `buildLayerDetectionPrompt(graph)` function (lines 57-66) constructs a textual prompt listing all file paths and requesting a JSON array describing layers, their names, descriptions, and path patterns. This prompt is sent to an LLM (such as Claude or GPT-4) for semantic analysis.

### Parsing and Applying LLM Responses

The `parseLayerDetectionResponse(response)` function extracts and validates the JSON from the LLM's reply. Subsequently, `applyLLMLayers(graph, llmLayers)` matches file nodes against the LLM-provided `filePatterns`. Any files remaining unmatched after this process are placed in an **Other** layer, preventing unclassified nodes in the final output.

## Practical Implementation Examples

The following TypeScript examples demonstrate how to invoke the layer detection pipeline using the Understand-Anything core package.

### Running the Heuristic Detector

```ts
import { detectLayers } from "./layer-detector.js";
import type { KnowledgeGraph } from "./types.js";

// `graph` is the knowledge graph produced by earlier analysis steps
const layers = detectLayers(graph);

// `layers` now contains entries like:
//   { id: "layer:api-layer", name: "API Layer", description: "...", nodeIds: [...] }
//   { id: "layer:service-layer", name: "Service Layer", description: "...", nodeIds: [...] }

```

### Falling Back to LLM Classification

```ts
import {
  buildLayerDetectionPrompt,
  parseLayerDetectionResponse,
  applyLLMLayers,
} from "./layer-detector.js";

// 1️⃣ Create a prompt for the LLM
const prompt = buildLayerDetectionPrompt(graph);

// 2️⃣ Send `prompt` to your chosen LLM (e.g., Claude, GPT-4) and obtain `llmResponse`
//    (implementation depends on your LLM client library)

// 3️⃣ Parse the response
const llmLayers = parseLayerDetectionResponse(llmResponse);
if (llmLayers) {
  // 4️⃣ Apply the LLM-defined layers to the graph
  const refinedLayers = applyLLMLayers(graph, llmLayers);
  // `refinedLayers` now contains the LLM-suggested layers such as API, UI, etc.
}

```

## Key Files and Architecture

The detection pipeline relies on three core components within the `understand-anything-plugin/packages/core/src/analyzer/` directory:

- **[`layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layer-detector.ts)** – Implements both heuristic detection (`LAYER_PATTERNS`, `matchFileToLayer`, `detectLayers`) and LLM-based refinement (`buildLayerDetectionPrompt`, `parseLayerDetectionResponse`, `applyLLMLayers`).
- **[`types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/types.ts)** – Defines the `KnowledgeGraph` and `Layer` interfaces consumed by the detection pipeline.
- **[`graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-builder.ts)** – Generates the knowledge graph that feeds into the layer detector.

## Summary

- The architecture-analyzer employs a **two-step hybrid strategy**: fast heuristic pattern matching followed by LLM-driven refinement.
- **Heuristic detection** uses the `LAYER_PATTERNS` constant in [`layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layer-detector.ts) to map directory names like `routes`, `controllers`, `services`, and `repositories` to API, Service, Data, UI, and Utility layers.
- The `matchFileToLayer` function processes file paths at lines 85-94, while `detectLayers` groups knowledge graph nodes into `Layer` objects.
- Unmatched files during heuristic detection fall into a **Core** layer; the LLM fallback processes these via `buildLayerDetectionPrompt` (lines 57-66) and `applyLLMLayers`.
- The system requires **zero manual configuration** to identify standard architectural layers across diverse project structures.

## Frequently Asked Questions

### What happens if a file doesn't match any predefined layer pattern?

Files that fail to match the `LAYER_PATTERNS` dictionary during heuristic detection are automatically assigned to a **Core** layer. If the LLM fallback is invoked and still cannot classify the file, it gets placed in an **Other** layer, ensuring complete graph coverage without unclassified nodes.

### How does the architecture-analyzer handle framework-specific directory structures?

The `LAYER_PATTERNS` constant includes common conventions across multiple frameworks (such as `routes` for Express.js, `controllers` for MVC frameworks, and `components` for React). For framework-specific edge cases, the LLM fallback analyzes the semantic context of file paths to suggest appropriate layer classifications beyond the predefined patterns.

### Can I customize the layer patterns for my specific project architecture?

While the source analysis focuses on the built-in `LAYER_PATTERNS` constant in [`layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layer-detector.ts), the modular architecture allows modification of the `LAYER_PATTERNS` dictionary or extension of the `matchFileToLayer` logic to include custom directory patterns. The LLM fallback further supports custom architectures by interpreting project-specific conventions from the provided file paths.

### What is the performance impact of the LLM fallback?

The heuristic detection runs synchronously and completes in milliseconds for typical repositories. The LLM fallback incurs latency only when triggered for ambiguous files, making an external API call to parse `buildLayerDetectionPrompt` outputs. This hybrid approach ensures optimal performance by reserving LLM calls for edge cases that pattern matching cannot resolve.