# How the Layer Detector Identifies Architectural Layers from File Structure in Understand-Anything > Discover how Egonex-AI Understand Anything's layer detector uses file structure, pattern matching, and LLM analysis to identify architectural layers. Learn more now. - Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) - Tags: internals - Published: 2026-06-14 --- **TLDR:** The layer detector identifies architectural layers by matching normalized file path segments against a predefined pattern table, then grouping files into logical layers with deterministic IDs, falling back to an LLM-based analysis when heuristic detection is insufficient. The **layer detector** in the [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) repository analyzes knowledge graph nodes to automatically **identify architectural layers from file structure**. This heuristic analyzer examines directory names within file paths to classify code into logical layers such as API, Service, Data, or UI layers, providing a structured view of codebase architecture without requiring manual annotation. ## How the Heuristic Layer Detection Works The detection process operates in three distinct phases defined in [`packages/core/src/analyzer/layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/analyzer/layer-detector.ts). Each phase transforms raw file paths into structured architectural abstractions. ### Pattern Definition in LAYER_PATTERNS The detector relies on a static mapping table called `LAYER_PATTERNS` (lines 16-67) that associates directory name patterns with architectural layer definitions. This table contains groups of directory names—such as "routes", "service", "model", or "ui"—each mapped to a specific layer name and description. The order of entries is significant: the detector uses a "first match wins" strategy when evaluating paths against these patterns. ### Path Matching with matchFileToLayer For every file node in the knowledge graph, the `matchFileToLayer` function (lines 80-96) normalizes the file path using forward slashes and lowercasing, then splits it into segments. Each segment is compared against every pattern in `LAYER_PATTERNS`, including plural form variations. The first directory segment that matches a pattern determines the file's architectural layer. If no pattern matches, the file is assigned to the default **Core** layer. ### Layer Grouping via detectLayers The `detectLayers` function (lines 101-144) orchestrates the classification process. It iterates through all file-type nodes, applies the path matching logic, and aggregates files by their discovered layer names. For each group, it constructs a `Layer` object containing: - A deterministic kebab-case ID formatted as `layer:` - The layer name and description (sourced from the pattern table when available) - An array of node IDs belonging to that layer Files lacking a `filePath` property are automatically placed in the **Core** layer during a secondary validation loop. ## LLM-Based Fallback Detection When heuristic pattern matching fails to capture complex architectural patterns, the detector provides an LLM-driven alternative that analyzes file paths using natural language understanding. ### Prompt Construction with buildLayerDetectionPrompt The `buildLayerDetectionPrompt` function (lines 50-67) generates a structured prompt containing every file path from the knowledge graph. This prompt requests the LLM to propose layer classifications and returns a JSON schema defining the expected response format, enabling structured parsing of the model's architectural suggestions. ### Response Parsing and Application The `parseLayerDetectionResponse` function (lines 77-120) validates and extracts layer definitions from the LLM's JSON response. Subsequently, `applyLLMLayers` (lines 122-184) maps these model-provided patterns onto the knowledge graph nodes, creating layer objects that follow the same structure as the heuristic output. This fallback path activates when the user explicitly requests LLM-driven inference or when the static pattern table fails to classify significant portions of the codebase. ## Practical Implementation Example The following TypeScript example demonstrates both heuristic detection and the LLM fallback workflow: ```typescript import { detectLayers, buildLayerDetectionPrompt } from '@understand-anything/core/analyzer/layer-detector.js'; import type { KnowledgeGraph } from '@understand-anything/core/types.js'; // Build a knowledge graph with file nodes const graph: KnowledgeGraph = { nodes: [ { id: '1', type: 'file', filePath: 'src/routes/user.ts' }, { id: '2', type: 'file', filePath: 'src/service/auth.ts' }, { id: '3', type: 'file', filePath: 'src/model/user.ts' }, { id: '4', type: 'file', filePath: 'src/ui/dashboard.tsx' }, { id: '5', type: 'file', filePath: 'src/util/logger.ts' }, ], edges: [], }; // Run heuristic detection const layers = detectLayers(graph); console.log(layers); /* Output: [ { id: 'layer:api-layer', name: 'API Layer', nodeIds: ['1'], ... }, { id: 'layer:service-layer', name: 'Service Layer', nodeIds: ['2'], ... }, { id: 'layer:data-layer', name: 'Data Layer', nodeIds: ['3'], ... }, { id: 'layer:ui-layer', name: 'UI Layer', nodeIds: ['4'], ... }, { id: 'layer:utility-layer', name: 'Utility Layer', nodeIds: ['5'], ... } ] */ ``` For LLM-driven classification: ```typescript import { buildLayerDetectionPrompt, parseLayerDetectionResponse, applyLLMLayers } from '@understand-anything/core/analyzer/layer-detector.js'; const prompt = buildLayerDetectionPrompt(graph); // Submit prompt to LLM... const llmLayers = parseLayerDetectionResponse(llmResponse); if (llmLayers) { const layeredGraph = applyLLMLayers(graph, llmLayers); } ``` ## Summary - The **layer detector** identifies architectural layers by matching directory names in file paths against the `LAYER_PATTERNS` table, with the first match determining the layer assignment. - Unmatched files and nodes without file paths default to the **Core** layer. - The `detectLayers` function produces structured layer objects with deterministic IDs (`layer:`) and associated node references. - An **LLM fallback** provides intelligent layer inference when heuristic patterns are insufficient, using `buildLayerDetectionPrompt`, `parseLayerDetectionResponse`, and `applyLLMLayers`. - All implementation resides in [`packages/core/src/analyzer/layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/analyzer/layer-detector.ts). ## Frequently Asked Questions ### What happens if a file doesn't match any layer pattern? Files that fail to match any entry in `LAYER_PATTERNS` are automatically assigned to the **Core** layer. This fallback ensures that all file nodes receive a layer classification even when directory names don't follow conventional architectural patterns. ### How does the layer detector handle files without file paths? During the layer construction phase in `detectLayers`, the detector performs a secondary validation loop that places any file node lacking a `filePath` property into the **Core** layer. This handles edge cases where knowledge graph nodes represent abstract or generated entities without physical file locations. ### Can I customize the layer patterns for my specific architecture? While the raw analysis focuses on the static `LAYER_PATTERNS` table, the architecture supports customization through the LLM-driven detection path. By using `buildLayerDetectionPrompt` and `applyLLMLayers`, you can inject custom layer definitions without modifying the core heuristic table, allowing project-specific architectural classifications. ### When should I use the LLM-driven detection instead of heuristics? Use **LLM-driven detection** when your codebase follows unconventional directory structures that don't match common patterns like "routes", "service", or "model", or when you need to identify domain-specific architectural layers that aren't covered by the static `LAYER_PATTERNS` table. The heuristic approach remains faster and more deterministic for standard architectures.