# How the Layer-Detector Identifies API, Service, and Data Layers in Understand-Anything

> Discover how Understand-Anything's layer-detector identifies API, Service, and Data layers using directory keywords and pattern matching for clear architectural insights.

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

---

**The layer-detector uses a two-stage heuristic that matches directory name keywords against ordered patterns in `LAYER_PATTERNS`, falling back to a generic Core layer for unmatched files, with optional LLM-driven classification for complex cases.**

The layer-detector in the Egonex-AI/Understand-Anything repository automatically discovers architectural layers by analyzing file paths within a knowledge graph. Implemented in [`understand-anything-plugin/packages/core/src/analyzer/layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/analyzer/layer-detector.ts), this module categorizes code into layers like API, Service, and Data through static pattern matching, with an optional LLM-based fallback for non-standard architectures.

## Pattern-Based Heuristic Matching with LAYER_PATTERNS

The core detection logic relies on a constant called `LAYER_PATTERNS` defined at lines 16-66 of [`layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layer-detector.ts). This ordered array maps directory-name keywords to canonical architectural layers, ensuring the first matching pattern wins when scanning file paths.

### Ordered Pattern Priority

Each entry in `LAYER_PATTERNS` supplies a set of directory patterns, a canonical layer name, and a descriptive label. Because the array is ordered, the detector prioritizes earlier matches, preventing ambiguous classifications when directory names could map to multiple layers. This deterministic approach ensures consistent results across repeated scans of the same codebase.

### Supported Architectural Layers

The predefined patterns cover standard architectural tiers including **API** (HTTP endpoints, route handlers), **Service** (business logic), **Data** (persistence, models), and **UI** (user interface components). Each pattern set includes common directory naming conventions—such as `api`, `services`, `data`, or `models`—allowing the detector to recognize both singular and plural directory names.

## Path-Segment Inspection and Normalization

When processing a file node, the layer-detector normalizes the file path and splits it into segments for inspection, as implemented in the `matchFileToLayer` function (lines 80-96).

### Directory Name Normalization

The detector processes the `filePath` property of each node, converting path segments into comparable strings. It scans each segment against the `LAYER_PATTERNS` entries, comparing directory names to identify which architectural layer owns the file.

### Plural Form Handling

The matching logic recognizes both singular and plural forms of directory names. If a segment equals a pattern exactly or matches its plural variant, the corresponding layer name is returned. Files that fail to match any pattern—or those lacking a `filePath` property—automatically fall back to the generic **Core** layer classification.

## The detectLayers Function and Core Fallback

The `detectLayers` function (lines 105-127) orchestrates the classification process across the entire knowledge graph.

### Grouping Nodes by Layer

The function iterates over all file-type nodes in the graph, invoking `matchFileToLayer` for each. It collects node IDs by their derived layer names, then constructs an array of `Layer` objects containing the layer name, description, and associated file references.

### Unmatched File Handling

Unmatched files and pathless nodes are deliberately placed in the **Core** layer. This ensures every file in the knowledge graph receives a classification while maintaining clear separation between recognized architectural tiers and generic application code.

## LLM-Driven Layer Detection Fallback

Beyond static heuristics, the module supports intelligent classification through LLM inference when directory structures deviate from standard conventions.

### Building the Detection Prompt

The `buildLayerDetectionPrompt` function generates a structured prompt containing the knowledge graph context, which can be sent to models like Claude or GPT-4. This allows the system to propose custom layer definitions when static patterns prove insufficient.

### Parsing and Applying LLM Responses

After receiving the LLM's JSON response, `parseLayerDetectionResponse` validates and extracts layer definitions. The `applyLLMLayers` function then applies these definitions to the graph nodes, overriding or supplementing the heuristic results. This hybrid approach combines the speed of pattern matching with the flexibility of AI-driven analysis.

## Practical Implementation Examples

Use the `detectLayers` function to classify an existing knowledge graph:

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

// Suppose `graph` is a KnowledgeGraph built from a project scan
const layers = detectLayers(graph);

// Print a summary
layers.forEach(l => {
  console.log(`🧱 ${l.name} – ${l.description} (${l.nodeIds.length} files)`);
});

/* Example output
🧱 API Layer – HTTP endpoints, route handlers, and API controllers (12 files)
🧱 Service Layer – Business logic and application services (8 files)
🧱 Data Layer – Data models, database access, and persistence (5 files)
🧱 Core – Core application files (20 files)
*/

```

For LLM-driven classification:

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

// Generate a prompt for the LLM (e.g. Claude, GPT‑4)
const prompt = buildLayerDetectionPrompt(graph);
// → send `prompt` to the LLM and obtain `response` (JSON string)

// Parse the LLM reply
const llmLayers = parseLayerDetectionResponse(response);
if (llmLayers) {
  const customLayers = applyLLMLayers(graph, llmLayers);
  // `customLayers` now reflects the LLM‑assigned layers
}

```

## Summary

- The layer-detector in [`understand-anything-plugin/packages/core/src/analyzer/layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/analyzer/layer-detector.ts) identifies architectural layers through ordered pattern matching against the `LAYER_PATTERNS` constant.
- Path segments are normalized and checked against directory keywords, with plural form support, defaulting unmatched files to the **Core** layer.
- The `detectLayers` function processes entire knowledge graphs, grouping file nodes by their derived layer classifications.
- Optional LLM integration via `buildLayerDetectionPrompt`, `parseLayerDetectionResponse`, and `applyLLMLayers` enables custom layer detection for non-standard project structures.
- Unit tests in [`understand-anything-plugin/packages/core/src/__tests__/layer-detector.test.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/__tests__/layer-detector.test.ts) validate expected behavior and edge-case handling.

## Frequently Asked Questions

### How does the layer-detector handle files that don't match any pattern?

Files that fail to match any entry in `LAYER_PATTERNS`, or those lacking a `filePath` property, are automatically assigned to the **Core** layer. This ensures complete graph coverage while distinguishing unrecognized files from explicitly categorized architectural layers.

### What happens when multiple patterns match a single file path?

The detector processes `LAYER_PATTERNS` as an ordered array and returns the first matching layer. This "first match wins" strategy prevents ambiguous classifications and ensures deterministic results across scans.

### Can the layer-detector identify custom architectural layers beyond API, Service, and Data?

Yes, through the LLM-driven detection path. By using `buildLayerDetectionPrompt`, `parseLayerDetectionResponse`, and `applyLLMLayers`, the system can propose and apply custom layer definitions based on AI analysis of the project's unique structure, bypassing the static `LAYER_PATTERNS` when necessary.

### Where can I find the unit tests for the layer-detector?

The unit tests are located at [`understand-anything-plugin/packages/core/src/__tests__/layer-detector.test.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/__tests__/layer-detector.test.ts). These tests illustrate expected behavior, validate edge-case handling, and ensure the `detectLayers` and `matchFileToLayer` functions correctly categorize files according to the defined architectural patterns.