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

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 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. 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

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

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 – Implements both heuristic detection (LAYER_PATTERNS, matchFileToLayer, detectLayers) and LLM-based refinement (buildLayerDetectionPrompt, parseLayerDetectionResponse, applyLLMLayers).
• types.ts – Defines the KnowledgeGraph and Layer interfaces consumed by the detection pipeline.
• 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 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, 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.

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