How domain-analyzer Extracts Business Domains and Process Flows: A Two-Stage Pipeline

The domain-analyzer extracts business domains and process flows by first performing a lightweight scan of the codebase to generate structured context, then using a specialized LLM agent to synthesize hierarchical business knowledge from that structural data.

The domain-analyzer in the Egonex-AI/Understand-Anything repository provides automated business domain discovery through a two-stage pipeline. It bridges the gap between raw source code and high-level business architecture by combining programmatic code analysis with LLM-driven knowledge synthesis. Understanding how domain-analyzer extracts business domains and process flows reveals how the tool maps technical implementations to business concepts without manual documentation.

Stage 1: Lightweight Code Scanning and Context Extraction

The first stage relies on understand-anything-plugin/skills/understand-domain/extract-domain-context.py, which programmatically traverses the project tree to build domain-context.json for downstream processing.

Respecting Project Boundaries and Source Filtering

The scanner respects .gitignore patterns and excludes directories defined in SKIP_DIRS (lines 22-48), ensuring build artifacts and dependencies are ignored. It processes only files matching extensions in SOURCE_EXTENSIONS, focusing analysis on actual source code rather than generated files or binary assets.

Detecting Entry Points Across Frameworks

Using the regex collection ENTRY_POINT_PATTERNS (lines 68-115), the scanner identifies entry points including HTTP routes, CLI commands, event listeners, cron jobs, GraphQL resolvers, and gRPC services. Each match records the file path, line number, entry type, code snippet, and description, creating a comprehensive map of how external actors interact with the system.

Extracting File Signatures and Metadata

For high-value files identified through "priority keywords," the scanner extracts file signatures—lightweight summaries of exports, imports, line counts, and code previews (lines 48-56, 67-99). It also pulls project metadata from package.json, pyproject.toml, and README.md files (lines 59-69). The final JSON output is truncated to respect MAX_OUTPUT_BYTES limits (lines 43-73) to ensure LLM compatibility.

Stage 2: LLM-Driven Domain Synthesis

The second stage occurs in understand-anything-plugin/agents/domain-analyzer.md, where an LLM agent consumes the structured context and infers business meaning using explicit reasoning rules.

Input Sources and Knowledge Graph Integration

The agent accepts either freshly generated domain-context.json or an existing knowledge-graph.json (lines 13-20), allowing iterative refinement of domain models. This flexibility supports both initial discovery and updates to existing business domain documentation as the codebase evolves.

Inferring Business Domains, Flows, and Steps

From the structural data, the LLM infers three hierarchical concepts:

• Business Domains: High-level areas like "Order Management" or "User Authentication"
• Business Flows: Concrete processes such as "Create Order" or "Process Refund" derived from entry points like HTTP routes or CLI commands
• Business Steps: Individual actions mapped to specific source file locations and line ranges within the implementation

Schema Enforcement and Validation Rules

The output follows a strict JSON schema (lines 27-92) where nodes represent domains, flows, and steps, with edges defining their relationships. The agent enforces validation rules including: every flow must connect to a domain, steps use weight ordering for sequencing, and all IDs follow kebab-case convention. These constraints ensure consistent, navigable domain graphs that validate against packages/core/src/__tests__/domain-types.test.ts.

Running the Domain Analyzer Pipeline

Execute the extraction pipeline using the following commands.

First, run the lightweight scanner:

python understand-anything-plugin/skills/understand-domain/extract-domain-context.py /path/to/my-app

This generates .understand-anything/intermediate/domain-context.json containing the file tree, entry points, and metadata.

Then invoke the Domain Analyzer agent:

understand --skill domain-analyzer \
  --input .understand-anything/intermediate/domain-context.json \
  --output .understand-anything/intermediate/domain-graph.json

The agent processes the context and emits domain-graph.json containing the structured business domain model with nodes and edges as defined in the agent specification.

Summary

• The domain-analyzer operates through two distinct phases: programmatic scanning and LLM synthesis
• Stage 1 uses extract-domain-context.py to identify entry points, file signatures, and metadata while respecting .gitignore and SKIP_DIRS
• Stage 2 employs the Domain Analyzer agent to infer business domains, flows, and steps from structural data according to the schema in domain-analyzer.md
• The pipeline enforces strict validation rules including kebab-case IDs, mandatory domain-flow relationships, and weight-ordered steps
• Output validates against domain type definitions in packages/core/src/__tests__/domain-types.test.ts and follows the design specification in docs/superpowers/specs/2026-04-01-business-domain-knowledge-design.md

Frequently Asked Questions

What file types does the domain-analyzer scanner process?

The scanner only processes files matching extensions defined in SOURCE_EXTENSIONS while ignoring directories listed in SKIP_DIRS and patterns in .gitignore (lines 22-48 of extract-domain-context.py). This typically includes source code files like .py, .js, .ts, and .java, while excluding build artifacts, dependencies, and generated files.

How does the domain-analyzer identify business processes from code?

The analyzer detects entry points such as HTTP routes, CLI commands, event listeners, and cron jobs using regex patterns in ENTRY_POINT_PATTERNS (lines 68-115). The LLM agent then maps these technical entry points to business flows by analyzing the file signatures, metadata, and context surrounding each entry point in the domain-context.json file.

Can the domain-analyzer update existing domain models?

Yes. The Domain Analyzer agent can accept either a fresh domain-context.json from the scanner or an existing knowledge-graph.json (lines 13-20 of domain-analyzer.md). This allows incremental updates to business domain documentation as the codebase evolves, supporting iterative refinement of the domain graph.

What validation rules ensure the quality of the generated domain graph?

The output must follow a strict schema where every flow connects to a domain, steps include weight ordering for sequence, and all IDs use kebab-case format. These rules are defined in the agent specification (lines 27-92) and validated against the domain type definitions in packages/core/src/__tests__/domain-types.test.ts, ensuring consistent hierarchical structure.

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