/omm-scan

name: omm-scan
description: Scan codebase architecture and generate/update .omm/ documentation. Use when the user says "omm scan", "scan architecture", "update architecture", "refresh diagrams".

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

| Perspective | When to create | What it answers | | --- | --- | --- | | `overall-architecture` | **Always** | What exists and how pieces relate | | `request-lifecycle` | Any server/API | How a request enters and gets handled end-to-end | | `data-flow` | Any data processing, DB usage | Where data comes from, transforms, and lands | | `dependency-map` | Complex module graph | What depends on what, what's shared | | `external-integrations` | External APIs/services | What the system connects to and why | | `state-transitions` | Stateful features (frontend or backend) | How state changes and what triggers it | | `route-page-map` | Frontend with routing | Page structure and navigation flow | | `command-surface` | CLI tools | Command hierarchy and dispatch | | `extension-points` | Plugin/extension systems | Extension architecture and registry | | `pipeline` | ML/data pipelines | Stage topology and data flow | | `orchestration` | Event-driven/queue systems | Publisher, subscriber, broker topology | | `storage` | 2+ storage systems | Storage topology (DB, cache, queue, object store) |

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.

   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:

   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, separ