How Egonex-AI Automatically Identifies and Color-Codes Architectural Layers

Egonex-AI automatically identifies architectural layers by scanning file paths against prioritized heuristic patterns in layer-detector.ts, then color-codes them using CSS custom properties derived from theme presets defined in presets.ts and applied via theme-engine.ts.

Egonex-AI's Understand-Anything repository transforms static code analysis into interactive visualizations by mapping source files to logical architectural layers and rendering them with consistent, theme-aware colors. The system employs a two-stage pipeline that first classifies code into layers such as API, Service, or Data based on directory naming conventions, then paints each layer using semantic color variables. This article examines the source code implementation of how architectural layers are automatically identified and color-coded by Egonex-AI.

Heuristic Layer Detection in layer-detector.ts

The classification engine lives in layer-detector.ts, where the detectLayers function processes the KnowledgeGraph produced during static analysis. This function iterates over every file node and evaluates its directory path against a prioritized list of regex-free patterns stored in LAYER_PATTERNS.

Pattern Matching Against Directory Names

When the analyzer encounters a file path, it segments the path and checks for folder names that indicate architectural responsibility. Common patterns include folders named routes mapping to the API Layer, service to the Service Layer, and model to the Data Layer. The patterns are evaluated in priority order, ensuring that the first match determines the layer assignment.

Files that match a specific pattern are grouped under that layer's metadata, which tracks the layer name and the collection of associated node IDs.

Fallback to the Core Layer

Files that fail to match any pattern in the LAYER_PATTERNS list are not left unclassified. Instead, the detector assigns them to a default Core layer, ensuring that every node in the graph receives a layer designation. This guarantees complete coverage across heterogeneous codebases where some files may not follow conventional directory structures.

Theme-Based Color Assignment

Once layers are detected, the visualization layer assigns colors dynamically through a theming system that separates aesthetic configuration from detection logic. This prevents hard-coded colors in the renderer and allows instant theme switching without re-analyzing the codebase.

Preset Color Palettes in presets.ts

Color definitions reside in presets.ts, which exports a PRESETS array containing theme configurations such as dark-gold. Each preset declares a semantic color map where keys like node-endpoint, node-service, and node-file map to specific hex values (e.g., "node-endpoint": "#fdba74"). These semantic keys correspond to the architectural layers identified during detection, ensuring that the API Layer consistently uses the node-endpoint color regardless of the active theme.

CSS Variable Injection via theme-engine.ts

The applyTheme function in theme-engine.ts bridges the preset definitions with the browser's rendering engine. When the dashboard mounts or the user switches themes, this function expands the preset's accent colors and injects them into the document root as CSS custom properties. It transforms the colors map from the preset into variables like --color-node-endpoint and --color-node-service.

The graph renderer then references these variables directly (e.g., var(--color-node-endpoint)) to paint nodes, ensuring that the Service Layer appears in the service color defined by the current theme while maintaining the overall aesthetic coherence of the selected preset.

Practical Implementation Examples

The following code demonstrates how to invoke the layer detection and theme application logic in your own tooling:

import { detectLayers } from '@understand-anything/core';

// `graph` is the KnowledgeGraph produced by the static analysis step
const layers = detectLayers(graph);
console.log(layers.map(l => `${l.name} → ${l.nodeIds.length} files`));

To apply a visual theme that color-codes these layers:

import { applyTheme } from './themes/theme-engine.ts';

applyTheme({
  presetId: 'dark-gold',   // one of the PRESETS defined in presets.ts
  accentId:  'gold',
  headingFont: 'serif',
});

Summary

• Heuristic detection in layer-detector.ts uses prioritized directory-name patterns to classify files into layers like API, Service, or Data, with non-matching files defaulting to the Core layer.
• The detectLayers function processes the KnowledgeGraph and returns layer metadata including node ID collections.
• Color management is decoupled from detection; presets.ts defines semantic color maps while theme-engine.ts injects them as CSS variables (--color-*).
• Themes like dark-gold map semantic keys (e.g., node-service) to hex values, allowing consistent layer coloring across different visual themes.

Frequently Asked Questions

What directory patterns does Egonex-AI use to identify architectural layers?

The system matches folder names against a prioritized list of regex-free patterns in LAYER_PATTERNS. Common identifiers include routes for the API Layer, service for the Service Layer, and model for the Data Layer. The order of patterns determines precedence when a path could match multiple categories.

How does Egonex-AI handle files that do not match any layer pattern?

Files that fail to match any heuristic pattern are automatically assigned to the default Core layer. This ensures 100% coverage of the codebase within the layer visualization system, preventing orphaned nodes in the knowledge graph.

Can the colors for specific architectural layers be customized?

Yes. Colors are defined in presets.ts within the PRESETS array, where each theme maps semantic keys like node-endpoint or node-service to specific hex values. Modifying these preset definitions or creating custom presets changes the colors used for each layer across the entire dashboard.

How does the system handle conflicting layer patterns?

The detectLayers function evaluates patterns in a strict priority order defined in LAYER_PATTERNS. The first match encountered in a file's path determines its layer assignment, ensuring deterministic classification even when directory names could theoretically belong to multiple architectural concepts.

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