What Is the Domain View and How Is It Extracted with /understand-domain?

The Domain view is a horizontal flow graph that visualizes the high-level business structure of a codebase, including logical domains, inter-domain flows, and process steps, extracted via the /understand-domain skill through a six-phase pipeline that scans source code and applies LLM reasoning.

The Egonex-AI/Understand-Anything repository provides an AI-powered architecture analysis tool that generates two primary perspectives on your codebase: the low-level structural view and the business-level Domain view. When you invoke the /understand-domain skill, the system orchestrates a multi-phase extraction pipeline that transforms raw source files into a domain-graph.json file, enabling rapid architectural insight without the noise of implementation details.

Understanding the Domain View

The Domain view abstracts away file-level complexity to reveal how business concepts interact. It consists of three core elements:

• Domains – Logical business areas such as Payments, User Management, or Inventory
• Flows – Data or action movements between domains, showing dependencies and interactions
• Steps – Individual processes or operations that comprise a flow

This representation appears by default in the Understand-Anything dashboard, offering stakeholders a clear picture of system architecture without requiring them to navigate source code.

How /understand-domain Extracts the Domain View

The skill executes a six-phase pipeline defined in understand-anything-plugin/skills/understand-domain/SKILL.md. Each phase handles specific concerns, from filesystem scanning to LLM-powered analysis.

Phase 0: Resolve Project Root

The system first determines the real repository root, including work-tree handling, to ensure generated files write to the correct location. According to the source code, this logic lives in SKILL.md lines 19-38.

Phase 1: Detect Existing Graph

The skill checks for a pre-existing knowledge-graph.json file. If found and the --full flag is not supplied, the extraction derives domain data directly from the existing graph, avoiding expensive file I/O. This optimization is implemented in SKILL.md lines 89-94.

Phase 2: Lightweight Scan

When no prior graph exists or --full is specified, the bundled Python script extract-domain-context.py executes. This scanner:

1. Walks the source tree respecting .gitignore patterns
2. Detects entry points (HTTP routes, CLI commands, cron jobs)
3. Samples a subset of files to collect exports and imports
4. Reads project-level metadata (e.g., package.json, README)

The output is written to <project-root>/.understand-anything/intermediate/domain-context.json. The core implementation spans lines 1-429 in extract-domain-context.py.

Phase 3: Derive from Knowledge Graph

If a knowledge-graph.json is present, the skill converts the node/edge data into the context format expected by the domain analyzer, bypassing the filesystem scan entirely. This logic appears in SKILL.md lines 112-121.

Phase 4: Domain Analysis

The domain-analyzer agent (prompt stored in agents/domain-analyzer.md) receives the context from Phase 2 or 3. It applies LLM reasoning to identify business domains, map flows between them, and define operational steps, emitting a structured domain-analysis.json. This phase is documented in SKILL.md lines 124-128.

Phase 5: Validate and Save

The output undergoes validation against the graph schema, which now includes domain, flow, and step types. The final artifact is saved as domain-graph.json under .understand-anything/. The constant DOMAIN_GRAPH_FILE in core/src/persistence/index.ts (line 150) defines this output path.

Phase 6: Dashboard Launch

The dashboard auto-loads domain-graph.json. In dashboard/vite.config.ts (lines 252, 299-300), the development server routes requests to serve this file, and the UI displays the Domain view by default, with an option to switch to the Structural view.

Running the /understand-domain Skill

You can trigger the extraction through the chat interface or manually invoke components for debugging.

Basic Usage

Reuse an existing knowledge graph if available:

/understand-domain

Force a fresh lightweight scan:

/understand-domain --full

Manual Preprocessing

For debugging or custom pipelines, run the scanner directly:

# From the repository root

python ./understand-anything-plugin/skills/understand-domain/extract-domain-context.py <project-root>

This produces <project-root>/.understand-anything/intermediate/domain-context.json.

Inspecting Results

View the generated domain graph:

cat <project-root>/.understand-anything/domain-graph.json | jq .

The JSON structure contains top-level arrays: domains, flows, and steps, each with id, name, description, and linking fields (source, target).

Key Implementation Files

File	Role
understand-anything-plugin/skills/understand-domain/SKILL.md	Orchestrates all six phases of the extraction pipeline
understand-anything-plugin/skills/understand-domain/extract-domain-context.py	Lightweight filesystem scanner that builds domain-context.json
understand-anything-plugin/packages/core/src/persistence/index.ts	Persists the final domain-graph.json (constant DOMAIN_GRAPH_FILE)
understand-anything-plugin/packages/dashboard/vite.config.ts	Serves domain-graph.json to the frontend and selects the Domain view by default
understand-anything-plugin/agents/domain-analyzer.md	LLM prompt that transforms raw context into structured domain graphs

Summary

• The Domain view represents business architecture as domains, flows, and steps, distinct from code-level structure.
• The /understand-domain skill executes a six-phase pipeline that resolves project roots, detects existing graphs, performs lightweight scans, and applies LLM analysis.
• Extraction leverages extract-domain-context.py for filesystem sampling and the domain-analyzer agent for business logic identification.
• Output is stored as domain-graph.json and automatically served to the dashboard via vite.config.ts routes.
• The system optimizes performance by deriving domain data from existing knowledge graphs when available, avoiding redundant file I/O.

Frequently Asked Questions

What is the difference between Domain view and Structural view?

The Domain view displays horizontal business flows between logical domains like Payments and User Management, while the Structural view shows the vertical hierarchy of files, folders, and code dependencies. The Domain view targets architectural decisions, whereas the Structural view aids implementation navigation.

How does the lightweight scan work without reading all files?

The extract-domain-context.py script uses intelligent sampling to detect entry points (HTTP routes, CLI commands) and reads only exported symbols and metadata files. It respects .gitignore patterns and projects the business structure from a representative subset rather than parsing every line of code, making it fast even on large repositories.

Where is the domain graph data stored?

The final output is saved as domain-graph.json in the .understand-anything/ directory at your project root. This path is defined by the DOMAIN_GRAPH_FILE constant in core/src/persistence/index.ts (line 150). Intermediate context data resides in .understand-anything/intermediate/domain-context.json.

Can I run the extraction manually without the AI skill?

Yes. You can invoke the Python scanner directly: python extract-domain-context.py <project-root>. This generates the intermediate context JSON without LLM processing. However, to produce the final domain-graph.json, you must either run the full skill (which triggers the domain-analyzer agent) or manually execute the analysis phase with the appropriate LLM prompt.

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