Technical Briefing: oh-my-mermaid

The Problem

AI-assisted development generates code faster than teams can document it. Without architecture diagrams, codebases become black boxes where new engineers spend hours reverse-engineering structure. This repository builds tools to reverse that flow: AI generates navigable Mermaid architecture diagrams from code, closing the gap between implementation and understanding.

What This Does

oh-my-mermaid scans codebases and generates multi-perspective architecture documentation as Mermaid diagrams. The core scanning logic lives in src/lib/store.ts, which 22 modules depend on as a hub - any change there has broad blast radius. Perspectives (overall-architecture, data-flow, etc.) are stored under .omm/ with recursive nesting: complex nodes spawn child diagrams. Key entry points are main in src/cli.ts:67 (reaches 100 functions), setup in src/lib/platforms/antigravity.ts:21 (7 functions), and startServer in src/server/index.ts:26 (2 functions). Duplicated 6-line blocks appear across src/commands/pull.ts, push.ts, share.ts and src/lib/platforms/antigravity.ts - 22 repeated instances requiring DRY extraction. The import graph has 55 modules with 97 edges and zero circular dependencies, indicating relatively clean module boundaries.

How It Is Wired

Execution starts at main in src/cli.ts:67, which routes to command handlers like commandLink, commandPush, etc. Internal call graph has 239 resolved call edges; ensureOmmForRead is called from 13 places, getOmmDir from 11, and readField from 9 - these central functions coordinate filesystem access. Paths to external effects: main -> commandLink uses fs.readFileSync; setup -> getPackageVersion also reads files. src/lib/cloud.ts handles credentials sync (syncHandleCredentials, getCredentialsPath, readCredentials, writeCredentials) across 7 calling files. The duplicated command logic (pull/push/share) represents the highest technical debt - extracting shared helpers would reduce the 22 repeated blocks and improve maintainability.

How To Use It

# Install globally
npm install -g oh-my-mermaid

# Register skills with AI tools
omm setup

# Scan a codebase (run inside Claude Code, Codex, Cursor, etc.)
/omm-scan

# View generated diagrams
omm view

# Configure language
omm config language ko

# Cloud workflow (private by default)
omm login && omm link && omm push

Configuration requires no environment variables beyond what your AI tool provides. The /omm-scan skill is invoked within your AI coding tool, not the terminal.

Real-World Use

A team onboards a new engineer who runs /omm-scan in Claude Code. The tool analyzes the repository and generates overall-architecture/diagram.mmd showing service boundaries, data-flow/ perspectives illustrating credential and API call patterns, and nested element diagrams for complex modules. The engineer navigates the .omm/ directory structure, clicking into main-process/ sub-diagrams for deeper inspection. Within minutes, the codebase's architecture is documented and navigable - no manual diagram drawing required.

Code Health & Issues

  • MEDIUM - Declare least-privilege permissions for GITHUB_TOKEN in .github/workflows/check-version-sync.yml; currently no permissions declared, token inherits repository default allowing any injected step to push commits.
  • MEDIUM - Enable Dependabot or Renovate; no update bot configured across 1,322 similar repositories means advisories go unpatched.
  • MEDIUM - Gate pull requests on dependency vulnerability scan; no dependency scan exists in CI workflows.
  • MEDIUM - Set persist-credentials: false on checkout in .github/workflows/release.yml; token stays in .git/config for later steps, enabling malicious postinstall scripts to read pushable credentials.
  • LOW - Add timeout-minutes to workflow jobs in .github/workflows/check-version-sync.yml; two jobs declare no timeout, risking overlap on a two-hourly schedule.

The Bottom Line

This repository successfully solves the architecture-documentation gap with a functional tool that generates navigable Mermaid diagrams from codebases. The codebase is structurally sound (no circular deps, no committed secrets) but carries moderate technical debt from duplicated command logic and a hub module (src/lib/store.ts) that demands careful stewardship. Teams wanting to reduce onboarding time and make AI-generated code auditable will find immediate value; organizations needing zero-maintenance CI hygiene should address the four medium-severity findings before production adoption.