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

> Customize Egonex AI architectural layer definitions beyond defaults. Edit LAYER_PATTERNS, rebuild the core package, and test to classify your codebase precisely.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-20

---

**Edit the `LAYER_PATTERNS` array 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) 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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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:

```bash
pnpm --filter @understand-anything/core build

```

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

```bash
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`:

```typescript
// 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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layer-detector.ts)**: Contains `LAYER_PATTERNS` array and `detectLayers` function that implements the first-match algorithm
- **[`types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/types.ts)**: Defines the `Layer` interface used by the detector for type safety across the core package
- **[`graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-builder.ts)**: Consumes `detectLayers` output to assign layer IDs to graph nodes in the knowledge graph
- **[`core/package.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/core/package.json)**: Houses build scripts and dependencies for the `@understand-anything/core` package
- **[`dashboard/src/store.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/dashboard/src/store.ts)**: Manages layer state for UI rendering in the dashboard application

## Summary

- **Modify `LAYER_PATTERNS`** in [`layer-detector.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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.