omm-scan — Perspective-Based Architecture Scanner

Purpose

Analyze the codebase and generate .omm/ architecture documentation using perspective-driven recursive analysis.

• A perspective is a top-level element — a distinct way to look at the architecture.
• Each element in a diagram gets analyzed recursively. If it has internal structure, it becomes a child element (subdirectory with its own diagram). If not, it stays a leaf.
• The filesystem determines nesting. Element IDs in diagrams match child directory names. The viewer resolves groups from the filesystem.

Prerequisites

command -v omm || npm install -g oh-my-mermaid

If the install fails, tell the user: "Please run npm install -g oh-my-mermaid in your terminal, then try again."

Step 0: Check Language

omm config language

Write field content (description, context, constraint, concern, todo, note) in the configured language. Default is English. Element IDs, directory names, and diagram node IDs are always English kebab-case.

Step 1: Explore the Codebase

Use Glob and Read to understand the project:

• Read package.json, pyproject.toml, or equivalent manifests
• List top-level directories to identify module boundaries
• Read key entry points (main, index, app files)
• Look for route definitions, service layers, database connections, external integrations

Step 2: Select Perspectives

From the catalog below, choose which perspectives are meaningful for this codebase.

Perspective Catalog

Don't force perspectives that don't exist in the code.

Step 3: Generate Perspectives with Recursive Drill-Down

For each selected perspective, follow this recursive process:

3a. Write the perspective diagram

Element IDs match child directory names. The viewer resolves nesting from the filesystem.

omm write <perspective> diagram - <<'MERMAID'
graph LR
    renderer["Renderer\nsrc/renderer/"]
    renderer -->|"IPC invoke/on"| main-process["Main Process\nsrc/main/"]
    main-process -->|"spawn PTY"| engine-system["Engine System\nsrc/main/engine/"]
    main-process -->|"read/write JSON"| data-store["Data Store\nsrc/main/store.ts"]
    main-process -->|"xterm.js"| terminal-dock["Terminal Dock\nsrc/renderer/src/panel/"]
MERMAID

3b. Write the other 6 fields

Each as a separate omm write command: description, context, constraint, concern, todo, note.

3c. Recursive drill-down: analyze every element

For every element in the diagram:

1. Analyze the code it represents (Glob + Read the relevant files/directories)

2. Write description for every node — no exceptions. This creates the element directory. Optionally write other fields (context, constraint, concern, todo, note) if relevant — Write in the configured language.

   bashCopy

   omm write <perspective>/<element-name> description - <<'EOF'
   (what this element does, which files/dirs it covers)
   EOF
   

3. Decide leaf or group:

   • Distinct internal components found → write a diagram and recurse deeper (it becomes a group)
   • No meaningful sub-components (single file, trivial wrapper, external system) → write remaining fields only (it stays a leaf)

4. If group — write diagram and recurse:

   bashCopy

   omm write <perspective>/<element-name> diagram - <<'MERMAID'
   graph LR
       (internal elements)
   MERMAID
   

   Then repeat step 3c for each element in this diagram.

Example recursion

overall-architecture (perspective)
  elements: renderer, main-process, engine-system, data-store, terminal-dock

  → analyze renderer (src/renderer/)
    → finds: App.tsx, components/, hooks/, stores/, world/
    → group → write diagram with: components, stores, world
      → analyze components → 15 .tsx files, no sub-structure → leaf
      → analyze stores → 4 zustand stores → leaf
      → analyze world → OfficeCanvas + PixiJS logic → leaf

  → analyze main-process (src/main/)
    → finds: ipc.ts, auth/, engine/, terminal-session-service.ts, store.ts
    → group → write diagram with: auth, engine, terminal-session
      → analyze auth → auth-service.ts, callback-server.ts → leaf
      → analyze engine → claude-code.ts, codex.ts → leaf

  → analyze data-store (src/main/store.ts)
    → single file → leaf

  → analyze terminal-dock (src/renderer/src/panel/)
    → TerminalDock.tsx, DockManager → leaf

Step 4: Summarize

Report what was created/updated and suggest omm view to view.

Diagram Rules

• Element IDs must match the child directory name. Use kebab-case: main-process, data-store, terminal-dock.

• Element labels use two-line format: name + file path, separated by \n:

  textCopy

  main-process["Main Process\nsrc/main/"]
  auth-service["Auth Service\nsrc/auth/service.ts"]
  

• Every edge must have a meaningful label: A -->|"why this connection exists"| B

• More elements in one diagram means you should recurse deeper.

• Use graph LR for most diagrams, graph TD for hierarchies.

• Use classDef for visual distinction when helpful:

  Style	Color	When to use
  external	#585b70	Third-party services outside your codebase
  concern	#f38ba8	Known risk or bottleneck
  entry	#89b4fa	Entry points (HTTP handler, CLI, queue consumer)
  store	#a6e3a1	Persistent storage (DB, cache, file system)

  textCopy

  classDef external fill:#585b70,stroke:#585b70,color:#cdd6f4
  classDef concern fill:#f38ba8,stroke:#f38ba8,color:#1e1e2e
  classDef entry fill:#89b4fa,stroke:#89b4fa,color:#1e1e2e
  classDef store fill:#a6e3a1,stroke:#a6e3a1,color:#1e1e2e
  

General Rules

• Write each field as a separate omm write command. Each omm write must be its own Bash tool call.
• Do not rewrite elements that haven't changed.
• Do not create circular references. A child element must never reference its parent.