How to Customize Architectural Layer Definitions in Egonex AI Beyond Default Types

Edit the LAYER_PATTERNS array in understand-anything-plugin/packages/core/src/analyzer/layer-detector.ts to add custom directory patterns, rebuild the core package with pnpm --filter @understand-anything/core build, and verify with the test suite to immediately apply new architectural layer classifications across your codebase.

Understand Anything (Egonex AI) automatically categorizes source files into architectural layers using hard-coded directory patterns defined in the core analyzer. While the system defaults to standard layers like API and Service, you can customize these definitions to recognize project-specific architectures such as GraphQL or Infrastructure layers. This guide provides the exact source file locations and build procedures required to extend the architectural analysis capabilities in the Egonex AI ecosystem.

How Layer Detection Works in Understand Anything

The architectural layer classification system relies on a hard-coded array of directory patterns located in understand-anything-plugin/packages/core/src/analyzer/layer-detector.ts. The detectLayers function iterates through every file path, normalizes it to lowercase, splits it on forward slashes, and returns the first matching pattern from the LAYER_PATTERNS array.

Default patterns include directories like routes, controller, handler, and endpoint for the API Layer, plus service, usecase, and business for the Service Layer. If no pattern matches, files fall into a generic "Core" layer. The order of patterns matters critically because the detector stops at the first match.

Step-by-Step Guide to Customizing Architectural Layers

Locate the Layer Configuration File

Navigate to understand-anything-plugin/packages/core/src/analyzer/layer-detector.ts in the Understand Anything repository. This TypeScript file contains the sole definition of LAYER_PATTERNS and the matchFileToLayer helper function that implements the matching logic.

Add Your Custom Layer Pattern

Insert a new pattern object into the LAYER_PATTERNS array before the generic catch-all entries. Each pattern requires:

• patterns: An array of directory name strings (the detector checks for exact matches or the segment plus "s")
• layerName: A display name for the UI and knowledge graphs
• description: Human-readable explanation of the layer's purpose

Rebuild and Verify Changes

After editing, rebuild the core package to compile your changes into the ESM bundle:

pnpm --filter @understand-anything/core build

Then run the test suite to ensure your new patterns work correctly without breaking existing detections:

pnpm --filter @understand-anything/core test

Example: Adding a GraphQL Layer Definition

To categorize all files under graphql/ directories into a dedicated layer, add this entry to LAYER_PATTERNS:

// In layer-detector.ts - insert before the "Utility Layer" or "Core" catch-all
{
  patterns: ["graphql", "gql"],
  layerName: "GraphQL Layer",
  description: "GraphQL schema files and resolver implementations",
}

The detection algorithm will now identify files like src/graphql/schema.ts or api/gql/resolvers/ as belonging to the GraphQL Layer. Once rebuilt, the dashboard will display a new tab containing these files, and the knowledge graph will include GraphQL Layer nodes with proper metadata from the types.ts interface.

Advanced Customization of Layer Detection Logic

For complex matching requirements beyond simple directory names, you can replace the matchFileToLayer helper function. This pure function accepts a file path and returns string | null, making it safe to modify without side effects.

Implement regex matching, glob patterns, or file-extension checks by copying the function to a new module, modifying the loop logic, and updating detectLayers to import your custom version. The graph-builder.ts file consumes detectLayers to attach layer IDs to nodes, so ensure your custom implementation maintains the expected return type to preserve compatibility with the graph generation pipeline.

Key Files for Architectural Layer Customization

Understanding the role of each source file helps navigate the customization process:

• layer-detector.ts: Contains LAYER_PATTERNS array and detectLayers function that implements the first-match algorithm
• types.ts: Defines the Layer interface used by the detector for type safety across the core package
• graph-builder.ts: Consumes detectLayers output to assign layer IDs to graph nodes in the knowledge graph
• core/package.json: Houses build scripts and dependencies for the @understand-anything/core package
• dashboard/src/store.ts: Manages layer state for UI rendering in the dashboard application

Summary

• Modify LAYER_PATTERNS in layer-detector.ts to add custom architectural layers beyond the default API and Service classifications
• Place custom patterns early in the array since the detectLayers algorithm returns the first match it encounters
• Rebuild the core package using pnpm --filter @understand-anything/core build to compile changes into the ESM bundle used by the CLI and dashboard
• Test thoroughly by running the core test suite to verify new patterns detect correctly without regressing existing layer classifications
• Extend detection logic by replacing matchFileToLayer for advanced use cases requiring regex or file-extension based matching

Frequently Asked Questions

Where are the default architectural layer patterns defined in Egonex AI?

The default patterns reside in the LAYER_PATTERNS constant array inside understand-anything-plugin/packages/core/src/analyzer/layer-detector.ts. This file contains hard-coded directory strings like "routes" and "service" that map to specific layer names, and the detectLayers function that implements the matching algorithm.

Can I customize layers without rebuilding the entire Understand Anything project?

No, you must rebuild the core package using pnpm --filter @understand-anything/core build because the layer detection logic is compiled into the ESM bundle consumed by both the dashboard and CLI components. The system does not support runtime configuration files for layer patterns, so changes require a fresh build to propagate.

How does the layer detection algorithm prioritize multiple matching patterns?

The detectLayers function implements a "first match wins" strategy. It normalizes file paths to lowercase, splits them by directory separators, and returns immediately when finding the first pattern match in the LAYER_PATTERNS array. Therefore, you should place specific custom layers before generic catch-all definitions like "Core" to ensure proper classification.

Is it possible to use regex or file extensions instead of directory names for layer detection?

Yes, but you must modify the matchFileToLayer helper function in layer-detector.ts. Replace the default string matching logic with regex or extension checks while maintaining the string | null return type. Since this is a pure function, you can safely extract it to a separate module for complex custom implementations without affecting the rest of the analyzer.

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