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:
-
Analyze the code it represents (Glob + Read the relevant files/directories)
-
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
-
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)
-
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, separated by \n:
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) |
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.