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

bash
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

bash
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.

bash
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)

1. 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.

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

1. 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)

1. If group — write diagram and recurse:

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

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

Example recursion

text
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:

text 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) |

text 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.