omm-scan

# 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) 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. ```bash 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: ```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.