How the Egonex AI Domain-Analyzer Extracts Business Logic from Code

The Egonex AI domain-analyzer transforms pre-processed code artifacts into a structured domain graph by clustering semantic cues from node summaries and tags into a three-tier hierarchy of domains, flows, and steps.

The domain-analyzer is a specialized agent within the Egonex-AI/Understand-Anything repository that converts structural code metadata into high-level business logic representations. Unlike traditional static analysis tools that scan raw syntax trees, this agent operates on language-agnostic preprocessing dumps to identify how technical implementations map to business concerns. It outputs a machine-readable JSON model that powers the plugin’s "Domain View" dashboard, enabling stakeholders to explore application logic without reading source files.

Input Architecture and Data Sources

The domain-analyzer never parses raw source code directly. Instead, it consumes pre-computed artifacts generated by earlier pipeline stages.

According to [agents/domain-analyzer.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/domain-analyzer.md), the agent accepts two input variants:

• domain-context.json – A lightweight dump containing the file tree, entry points, and import/export maps, generated when no prior knowledge graph exists.
• knowledge-graph.json – A comprehensive structural graph produced by the project-scanner and file-analyzer agents, containing node summaries, semantic tags, and relationship data.

This design decouples the business logic extraction from language-specific parsing, allowing the agent to focus purely on semantic clustering.

The Three-Tier Business Hierarchy

The analyzer constructs a strict hierarchy that mirrors how organizations conceptualize software functionality. Each level uses kebab-case IDs and includes a complexity flag (simple, moderate, or complex) to indicate implementation depth.

Business Domain

The highest abstraction representing a distinct business area (e.g., Order Management or User Authentication). Domains aggregate related flows and define the boundaries of business responsibility.

Business Flow

A concrete process within a domain that delivers business value (e.g., Create Order or Process Payment). Flows typically map to user journeys or API endpoints and contain ordered collections of steps.

Business Step

An atomic action implementing part of a flow (e.g., Validate Input or Save to Database). Steps reference specific file paths and line ranges from the original source code, providing traceability from business logic back to implementation.

Semantic Extraction Logic

The agent derives business entities by analyzing semantic cues embedded in the pre-processed context:

• Node summaries generated by explain agents often contain domain-specific terminology (e.g., "payment processing", "inventory check").
• Structural tags (such as api, service, or db) attached to code nodes are aggregated to infer domain membership.
• Entry-point patterns like HTTP routes (POST /api/orders), CLI commands, or event names are mapped directly to Business Flows.

By clustering nodes with shared vocabulary and connectivity patterns, the analyzer automatically groups technical components into their corresponding business concerns without manual annotation.

Edge Construction and Relationship Mapping

After establishing nodes, the agent constructs a directed graph using three relationship types defined in the output schema:

• contains_flow – Links a Business Domain to its child Business Flows with a weight of 1.0.
• flow_step – Connects a Flow to its ordered Steps; edge weights encode execution sequence using monotonically increasing values from 0.1 to 1.0.
• cross_domain – Captures interactions between different domains (e.g., User Authentication invoking Order Management), allowing the model to represent real-world coupling while maintaining hierarchical clarity.

This edge schema ensures acyclic step sequences within flows while preserving valid cross-domain cycles present in the codebase.

Output Schema and Consumption

The final artifact is written to <project-root>/.understand-anything/intermediate/domain-analysis.json and adheres to a strict JSON contract. The output includes:

• Project metadata (name, languages, frameworks)
• Node arrays with IDs, types, summaries, tags, and domain-specific metadata
• Edge arrays defining relationships with directional indicators and weights

The Understand-Anything dashboard consumes this file to render interactive visualizations where users can navigate from high-level domains down to specific line ranges in the source code.

Practical Usage

Trigger the business logic extraction using the skill defined in [skills/understand-domain/SKILL.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-domain/SKILL.md):

# Run the full analysis pipeline (creates knowledge-graph.json first)

/understand

# Extract only the business domain view (requires existing knowledge graph)

/understand-domain

The skill automatically orchestrates preprocessing when domain-context.json or knowledge-graph.json is missing, then dispatches the domain-analyzer with the appropriate context.

Example Output Structure

Below is a truncated example of the JSON generated by the domain-analyzer:

{
  "project": { "name": "my-app", "languages": ["ts"], "frameworks": ["react"] },
  "nodes": [
    {
      "id": "domain:order-management",
      "type": "domain",
      "name": "Order Management",
      "summary": "Handles creation, update and tracking of customer orders.",
      "tags": ["order","e-commerce"],
      "complexity": "moderate",
      "domainMeta": {
        "entities": ["Order","Cart"],
        "businessRules": ["Order total must be > 0"]
      }
    },
    {
      "id": "flow:create-order",
      "type": "flow",
      "name": "Create Order",
      "summary": "Creates a new order from a shopping cart.",
      "tags": ["http","api"],
      "complexity": "simple",
      "domainMeta": { "entryPoint": "POST /api/orders", "entryType": "http" }
    },
    {
      "id": "step:create-order:validate-input",
      "type": "step",
      "name": "Validate Input",
      "summary": "Ensures cart items are in stock and user is authenticated.",
      "tags": ["validation"],
      "complexity": "simple",
      "filePath": "src/orders/create.ts",
      "lineRange": [12, 27]
    }
  ],
  "edges": [
    { "source": "domain:order-management", "target": "flow:create-order", "type": "contains_flow", "direction": "forward", "weight": 1.0 },
    { "source": "flow:create-order", "target": "step:create-order:validate-input", "type": "flow_step", "direction": "forward", "weight": 0.1 }
  ]
}

Summary

• The domain-analyzer operates on pre-processed JSON artifacts rather than raw source code, enabling language-agnostic business logic extraction.
• It organizes code into a three-tier hierarchy of Business Domains, Business Flows, and Business Steps, each with standardized metadata and complexity ratings.
• Semantic clustering of node summaries and tags automatically groups technical components into business concerns without manual mapping.
• The agent produces a directed graph with typed edges (contains_flow, flow_step, cross_domain) that model both hierarchical containment and cross-domain interactions.
• Output is consumed by the Understand-Anything dashboard to render navigable business logic views traceable to specific file paths and line ranges.

Frequently Asked Questions

Does the domain-analyzer parse raw source files directly?

No. According to the agent specification in agents/domain-analyzer.md, the analyzer exclusively consumes domain-context.json or knowledge-graph.json files generated by preceding pipeline stages. This architecture separates semantic extraction from language-specific parsing, allowing the agent to focus on business logic patterns rather than syntax trees.

What distinguishes a Business Flow from a Business Step?

A Business Flow represents a complete process that delivers business value, such as "Create Order" or "Send Notification," typically corresponding to API endpoints or user transactions. A Business Step is an atomic operation within that flow, such as "Validate Input" or "Query Database," representing a single logical action with a specific implementation in the codebase.

How does the analyzer determine which domain a piece of code belongs to?

The analyzer clusters code nodes based on semantic cues extracted from pre-generated summaries, structural tags (like api or service), and entry-point patterns. Nodes sharing domain-specific vocabulary (e.g., "payment," "inventory") and connectivity patterns are automatically grouped under the same Business Domain without requiring manual classification.

Can I run domain analysis without generating the full knowledge graph?

Yes. The /understand-domain skill defined in skills/understand-domain/SKILL.md can operate in lightweight mode using domain-context.json, which requires only a basic file-tree scan and entry-point analysis. However, for richest semantic extraction, the full knowledge-graph.json produced by the project-scanner and file-analyzer agents provides superior input data.

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