Obsidian Code MOC — Layered Architecture Visualization

---
description: Visualize a codebase as layered MOC (Map of Content) notes in Obsidian. Creates hierarchical depth via folder nesting + MOC notes at each zoom level — App Overview → Feature MOCs → Component notes → Internal method/utility notes. Simulates hierarchy in Obsidian's flat graph view.
disable-model-invocation: true
allowed-tools: Bash Read
---

# Obsidian Code MOC — Layered Architecture Visualization

Create a hierarchical Map of Content structure in Obsidian that simulates zoom levels for navigating a codebase.

## Arguments

`$ARGUMENTS` — path to a file or directory to visualize. If empty, ask the user what to visualize.

## The 4-Tier Hierarchy

```
project/
├── App Overview.md              ← Tier 0: top-level MOC
├── features/
│   ├── Feature A MOC.md         ← Tier 1: feature MOCs
│   ├── Feature B MOC.md
│   └── ...
├── components/
│   ├── ComponentX.md            ← Tier 2: class/module notes
│   ├── ComponentY.md
│   └── ...
└── internals/
    ├── methodOrHook.md          ← Tier 3: method/hook/utility notes
    └── ...
```

Each tier links **down** to children and **up** to parent MOC, creating bidirectional navigable depth.

## Steps

### 1. Determine scope

- If `$ARGUMENTS` is a file: decompose that file into its internal hierarchy
- If `$ARGUMENTS` is a directory: decompose the full codebase
- If empty: ask the user

### 2. Determine project compartment

- Infer project name from git repo name or directory name
- All notes go under: `<project-name>/`
- Subfolder structure: `features/`, `components/`, `internals/`

### 3. Analyze and decompose the codebase

This is the critical step — you must identify the **semantic layers**, not just the file tree.

#### 3a. Identify Features (Tier 1)
Group the codebase into 3-8 features/concerns. These are user-facing capabilities or major subsystems, NOT individual files. Examples:
- "Authentication", "Dashboard", "Payments"
- "Audio Analysis", "Freestyle Mode", "Extraction Pipeline"

#### 3b. Identify Components (Tier 2)
Within each feature, identify the classes/modules that implement it. Each component belongs to exactly one feature (its primary home), but may be referenced by others.

#### 3c. Identify Internals (Tier 3)
For each component, identify notable methods, hooks, utilities, or helper functions that are worth their own note. Only create Tier 3 notes for:
- Methods with non-trivial logic (algorithms, state machines, complex transformations)
- Shared utilities called by multiple components
- Hooks or event handlers with important side effects

Skip trivial getters/setters/formatters — mention them inline in the Component note instead.

### 4. Create notes via Obsidian MCP — bottom up

Create notes from the bottom tier up so wikilinks resolve correctly.

#### Tier 3 — Internal notes (`internals/` folder)

```markdown
# methodName

One-line purpose.

## Parent
- [[ComponentName]] (in [[Feature Name MOC]])

## Signature
`function methodName(param: type): returnType`

## Algorithm
Brief description of the non-obvious logic (2-4 lines max).

## Uses
- [[other_internal_1]]
- [[other_internal_2]]

## Used by
- [[caller_internal]]
```

#### Tier 2 — Component notes (`components/` folder)

```markdown
# ComponentName

One-line purpose.

## Feature
- [[Feature Name MOC]]

## File
`path/to/file.js`

## Key Methods
- [[notable_method_1]] — one-line description
- [[notable_method_2]] — one-line description
- `trivialMethod()` — inline description (no separate note)

## Dependencies
- [[OtherComponent]] — what it uses from it
- [[AnotherComponent]] — what it uses from it

## Depended on by
- [[ConsumerComponent]] — what it provides
```

#### Tier 1 — Feature MOC notes (`features/` folder)

```markdown
# Feature Name MOC

2-3 sentence description of what this feature does and why it exists.

## Overview
- [[App Overview]]

## Components
- [[Component1]] — role in this feature
- [[Component2]] — role in this feature

## Data Flow
Brief description of how data moves through this feature's components (3-5 lines, use → arrows).

## Cross-feature Dependencies
- Depends on [[Other Feature MOC]] for X
- Provides Y to [[Another Feature MOC]]
```

#### Tier 0 — App Overview (`project root`)

```markdown
# App Overview

2-3 sentence architectural summary.

## Features
- [[Feature A MOC]] — one-line description
- [[Feature B MOC]] — one-line description
- [[Feature C MOC]] — one-line description

## Architecture Layers
Group features by layer (e.g., "Frontend", "Backend", "Pipeline", "Shared").

## Key Data Structures
List the 3-5 most important data structures with brief descriptions. Link to the component that owns each.

## Entry Points
- User interaction starts at [[ComponentX]]
- CLI entry at [[ComponentY]]
```

### 5. Report to user

Tell the user:
- Total notes created, broken down by tier
- The vault path and folder structure
- Suggest opening Obsidian's graph view with the following tips:
  - Use "Groups" to color-code by folder (features=blue, components=green, internals=orange)
  - MOC notes will appear as high-degree hubs; internals as leaf nodes
  - The visual clusters correspond to features