# How the Domain-Analyzer Agent Extracts Business Domains and Flows from Code in Understand-Anything

> Learn how the domain-analyzer agent extracts business domains and flows from code by leveraging LLMs to create structured business domain graphs from source code snapshots.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: deep-dive
- Published: 2026-06-28

---

**The domain-analyzer agent transforms raw source code into a structured business domain graph by first generating a lightweight context snapshot, then using an LLM to infer hierarchical relationships (domains → flows → steps) based on detected entry points and file signatures.**

The `domain-analyzer` agent is the core engine behind the **Business Domain Knowledge** feature in the [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) repository. Rather than parsing entire source files directly, the agent receives a curated, pre-filtered context that allows it to focus on semantic business relationships while keeping token usage minimal. This article breaks down the exact four-stage pipeline implemented in the source code, from the initial Python scanner to the final JSON graph output.

## The Four-Stage Extraction Pipeline

The extraction process follows a strict orchestration defined in [`understand-anything-plugin/skills/understand-domain/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-domain/SKILL.md). Each stage prepares the inputs necessary for the LLM to reason about business logic without drowning in implementation details.

### 1. Context Preparation

The skill first determines whether to use an existing knowledge graph or generate fresh context. If [`./.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/./.understand-anything/knowledge-graph.json) exists, the agent receives that graph as **Option B** context. Otherwise, the Python script [`extract-domain-context.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/extract-domain-context.py) executes to create [`domain-context.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-context.json)—a lightweight snapshot containing the file tree, entry-point detections, file signatures, and metadata.

This scanner runs via the `--full` flag to force a fresh scan, detecting entry points through a series of regular expressions (`ENTRY_POINT_PATTERNS`) defined in lines 68-115 of [`extract-domain-context.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/extract-domain-context.py). These patterns identify:

- **HTTP routes** (Express, Koa, FastAPI)
- **CLI commands** (commander, argparse, yargs)
- **Event listeners** (Kafka, RabbitMQ, EventEmitter)
- **Cron jobs** (node-cron, Python schedule, @Cron decorators)
- **GraphQL resolvers**

### 2. Prompt Loading and Schema Definition

The skill loads the agent prompt from [`agents/domain-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/domain-analyzer.md). This markdown file serves as the contract between the orchestration layer and the LLM, defining:

- The **three-level hierarchy**: Domain → Flow → Step
- The exact JSON schema for the output graph
- Hard validation rules (monotonic edge weights between 0-1, kebab-case IDs, required metadata fields)

By externalizing the prompt to a dedicated markdown file, the system allows prompt versioning independent of the skill logic.

### 3. LLM-Driven Analysis

With the context prepared and prompt loaded, the skill dispatches a sub-agent containing:

1. **Entry points** with file paths, line numbers, match snippets, and types (HTTP, CLI, cron, etc.)
2. **File signatures** detailing exports, imports, and line counts that hint at business objects and service boundaries
3. **Metadata** from [`package.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/package.json), [`README.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/README.md), and other project files providing high-level domain clues

The LLM receives this *clean, bounded* view rather than raw source files, enabling it to focus on business semantics. The context explicitly excludes noise like `node_modules` or build artifacts, ensuring crisp reasoning within token limits.

### 4. Graph Construction and Validation

Guided by the schema in [`agents/domain-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/domain-analyzer.md), the LLM emits [`domain-analysis.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-analysis.json) containing:

- **Domain nodes** (`type: "domain"`) with summaries, tags, complexity scores, and `domainMeta` blocks describing entities and business rules
- **Flow nodes** (`type: "flow"`) linked to parent domains via `contains_flow` edges
- **Step nodes** (`type: "step"`) linked to flows via `flow_step` edges with monotonically increasing weights (0.0 to 1.0) encoding execution order
- **Cross-domain edges** capturing interactions between separate business domains

After validation, the result is saved as [`./.understand-anything/domain-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/./.understand-anything/domain-graph.json), triggering the dashboard to switch to **Domain View**.

## Key Source Files and Their Roles

| File | Purpose |
|------|---------|
| [`understand-anything-plugin/agents/domain-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/domain-analyzer.md) | Defines the LLM prompt, hierarchical schema, and validation rules (lines 29-90 contain the edge-weight specifications). |
| [`understand-anything-plugin/skills/understand-domain/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-domain/SKILL.md) | Orchestrates the workflow: decides context source, dispatches the sub-agent, and handles output validation. |
| [`understand-anything-plugin/skills/understand-domain/extract-domain-context.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-domain/extract-domain-context.py) | Python scanner that generates [`domain-context.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-context.json) via regex-based entry point detection. |

## Practical Examples

### Running the Domain Analysis

Trigger the full extraction pipeline from your project root:

```bash

# Force a fresh scan (bypass existing knowledge graph)

understand-domain --full

```

This executes the four-stage pipeline:
1. Generates [`./.understand-anything/intermediate/domain-context.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/./.understand-anything/intermediate/domain-context.json) via [`extract-domain-context.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/extract-domain-context.py)
2. Loads the prompt from [`agents/domain-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/domain-analyzer.md)
3. Dispatches the LLM sub-agent with the context
4. Writes [`domain-analysis.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-analysis.json), validates it, and saves the final [`domain-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-graph.json)

### The Generated Context (LLM Input)

The Python scanner produces a JSON structure that serves as the LLM's window into the codebase:

```json
{
  "projectRoot": "/path/to/project",
  "fileTree": ["src/orders/controller.ts", "src/payments/service.ts"],
  "entryPoints": [
    {
      "file": "src/orders/controller.ts",
      "line": 12,
      "type": "http",
      "description": "Express/Koa route",
      "match": "router.post('/orders', createOrder)",
      "snippet": "router.post('/orders', createOrder);\n..."
    },
    {
      "file": "src/cron/jobs.py",
      "line": 34,
      "type": "cron",
      "description": "Cron schedule",
      "match": "@Cron('0 0 * * *')",
      "snippet": "@Cron('0 0 * * *')\nasync def daily_summary():\n ..."
    }
  ],
  "fileSignatures": [
    {
      "file": "src/orders/controller.ts",
      "exports": ["createOrder", "getOrder"],
      "imports": ["orderService", "authMiddleware"],
      "lines": 120,
      "preview": "export async function createOrder(req, res) { ... }"
    }
  ],
  "metadata": {
    "package.json": { "name": "my-shop", "description": "E-commerce platform" }
  }
}

```

### The Output Domain Graph (LLM Output)

The final artifact represents business concepts as a traversable graph:

```json
{
  "nodes": [
    {
      "id": "domain:order-management",
      "type": "domain",
      "name": "Order Management",
      "summary": "Handles order creation, validation, and lifecycle.",
      "tags": ["order", "e-commerce"],
      "complexity": "moderate",
      "domainMeta": {
        "entities": ["Order", "Cart"],
        "businessRules": ["Inventory must be reserved before order is confirmed"]
      }
    },
    {
      "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 request payload matches the Order schema.",
      "tags": ["validation"],
      "complexity": "simple",
      "filePath": "src/orders/controller.ts",
      "lineRange": [12, 18]
    }
  ],
  "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 agent** does not parse raw source code directly; it receives a **pre-filtered context** generated by [`extract-domain-context.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/extract-domain-context.py) or an existing knowledge graph.
- The extraction follows a **four-stage pipeline**: context preparation, prompt loading, LLM-driven analysis, and graph construction.
- **Entry points** are detected via regex patterns in [`extract-domain-context.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/extract-domain-context.py) (lines 68-115) covering HTTP routes, CLI commands, cron jobs, and event listeners.
- The output follows a **strict three-level hierarchy** (Domain → Flow → Step) defined in [`agents/domain-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/domain-analyzer.md), with monotonic edge weights encoding step ordering.
- Final artifacts are saved to [`./.understand-anything/domain-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/./.understand-anything/domain-graph.json) for dashboard visualization.

## Frequently Asked Questions

### What triggers the domain-analyzer agent to run a fresh scan versus using an existing knowledge graph?

The skill checks for [`./.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/./.understand-anything/knowledge-graph.json) at startup. If the file exists, the agent uses it as **Option B** context. If the file is missing or the user passes the `--full` flag, the agent triggers [`extract-domain-context.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/extract-domain-context.py) to generate a new [`domain-context.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-context.json) from scratch.

### How does the agent identify business entry points without parsing every file manually?

The Python scanner [`extract-domain-context.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/extract-domain-context.py) uses predefined `ENTRY_POINT_PATTERNS` (regular expressions) to detect HTTP routes, CLI commands, cron decorators, event listeners, and GraphQL resolvers. These patterns extract the file path, line number, and code snippet for each entry point, creating a bounded context that hints at business boundaries without requiring full AST parsing.

### What is the significance of edge weights in the generated domain graph?

Edge weights represent **execution ordering** within flows. The `flow_step` edges connecting steps to their parent flows use monotonically increasing values between 0 and 1 (e.g., 0.1, 0.2, 0.9) to indicate sequence. The `contains_flow` edges between domains and flows use a weight of 1.0, serving as structural connectors rather than sequence indicators.

### Can the domain-analyzer agent handle repositories with multiple programming languages?

Yes. The [`extract-domain-context.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/extract-domain-context.py) scanner detects entry points across languages through its regex-based `ENTRY_POINT_PATTERNS`, which identify TypeScript/JavaScript HTTP frameworks, Python decorators, Go CLI patterns, and more. The resulting [`domain-context.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-context.json) normalizes these into a language-agnostic format, allowing the LLM to reason about business domains regardless of the underlying syntax.