Mirofy

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.png">
    <img src="assets/logo.png" alt="Mirofy — connect, model, insight" width="380">
  </picture>
</p>

<p align="center">
  <strong>Diagrams of your system that cite their sources — and say what they could not see.</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/mirofy-cli"><img src="https://img.shields.io/npm/v/mirofy-cli?style=flat-square&color=3b82f6&label=mirofy-cli" alt="mirofy-cli on npm"></a>
  <img src="https://img.shields.io/badge/license-MIT-3b82f6?style=flat-square" alt="MIT licensed">
  <img src="https://img.shields.io/badge/runtime%20dependencies-0-7c3aed?style=flat-square" alt="Zero runtime dependencies">
  <img src="https://img.shields.io/badge/conformance-85%20rows%20proved-3b82f6?style=flat-square" alt="85 conformance rows proved without a browser">
  <img src="https://img.shields.io/badge/output-one%20HTML%20file-7c3aed?style=flat-square" alt="Output is one HTML file">
</p>

<p align="center">
  <a href="https://hasan-laraib.github.io/Mirofy/gallery/architecture--classic.html">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="assets/viewer-hero-dark.png">
      <img src="assets/viewer-hero.png" alt="A rendered Mirofy artifact open in a browser: ten services coloured by role, grouped inside an AWS region and a security group, with a legend naming each role" width="880">
    </picture>
  </a>
</p>

<p align="center">
  <em>This is the whole product: one HTML file, open in a browser. Every colour
  in it is the system&rsquo;s own vocabulary &mdash; backend, database, cloud,
  security, message bus, external &mdash; and nothing else. Colour never marks
  where an arrow goes, only what a thing <strong>is</strong>.</em>
  <br>
  <strong><a href="https://hasan-laraib.github.io/Mirofy/gallery/architecture--classic.html">Open this exact file ↗</a></strong> &mdash;
  click any node for its evidence, trace what reaches it, search it, present it.
</p>

---

## What it is

Point Mirofy at a repository. It reads the code into an **evidence graph**,
builds a **model** from that graph, and compiles the model into **one HTML
file** you can open, search, share and check.

Every relationship it draws can answer one question: *what is the evidence for
this?* Each carries the file, the line range and the commit it came from. Where
nothing is known, the diagram **says so** instead of filling the gap.

<p align="center">
  <img src="assets/pipeline.svg" alt="scan to model to compile to layout to render" width="880">
</p>

Run it against this repository and you get this — not a mock-up, and not drawn
by hand:

<p align="center">
  <a href="https://hasan-laraib.github.io/Mirofy/self-model.html"><img src="assets/self-model.svg" alt="Mirofy's own architecture, derived from its own source code: twelve packages and the imports between them" width="820"></a>
</p>

<p align="center">
  <em>Every box is the same colour here, and that is the point. All twelve of
  these are the same thing — a package, derived from a manifest — so there is
  nothing for colour to say, and it says nothing. The picture at the top is
  colourful because that system genuinely has six kinds in it. A tool that
  tinted these boxes to look livelier would be inventing a distinction it had
  not found.</em>
  <br>
  <strong><a href="https://hasan-laraib.github.io/Mirofy/self-model.html">Open the live one ↗</a></strong> — click any
  node for the file, line range and commit behind it.
</p>

## Install

**Nothing to install** — one command, and a diagram opens:

```bash
npx mirofy-cli map .    # YOUR repository, mapped, in one command
npx mirofy-cli demo     # a finished artifact, to see what this produces
npx mirofy-cli init     # a starter document of your own to edit
npx mirofy-cli render architecture architecture.json
```

**Give it to your agent instead** — one line, and the skill installs for Claude
Code, Cursor, Gemini CLI, Amp and a dozen others:

```bash
npx skills add Hasan-Laraib/Mirofy
```

Then ask: *map this repository's architecture*. Your agent reads
[`SKILL.md`](packages/core/SKILL.md) and drives the same CLI.

**In Claude Code**, the plugin carries both the skill and the MCP server:

```
/plugin marketplace add Hasan-Laraib/Mirofy
/plugin install mirofy@mirofy
```

Every one of these routes is the same package. The agent never draws the
diagram — it runs the CLI you would have run, which is why nothing it reports
can drift from what the CLI reports.

`map` runs the whole pipeline in the directory you point it at — scan, model,
compile, layout, render — and writes `architecture.html` next to your code.
`map --out <dir>` sends the diagram and the intermediates there instead, so
nothing lands in your repository; without it the intermediates go to
`<target>/scan`. Naming an output path still wins over both. It works on a repository that declares no
workspaces: where there are no packages to draw, it models the **source
directories** and the imports between them.

### What it reads

**JavaScript and TypeScript** imports · **Python** imports · **Go** imports ·
**Java** imports · **Rust** imports · **Kotlin** imports ·
`package.json` workspaces · Express and Next routes · `docker-compose`.

That is the whole list, and the list is the point. Everything else is
**reported, not skipped**: `coverage.md` names every file no adapter opened,
grouped by type, and `map` says so on its way out when the unread files
outnumber the read ones. Point it at a Ruby repository and you get an honest
empty answer naming every unread `.rb` file — not a confident small one drawn
from the two JavaScript files in an `examples/` folder.

Python resolves by **file existence**, not by convention: relative imports
against the importing file's directory, absolute ones against the repository
root and any directory that actually holds a package. A specifier that matches
two source roots is a gap naming both, because which one wins depends on
`sys.path`, which is configuration and not in the source.

Go resolves against the module path `go.mod` **declares**, and decides the
standard library the way the toolchain does — a first path segment containing a
dot is a domain, and a domain means a module fetched from somewhere. Java
builds its index from the `package` statements files **declare**, not from
directory layout: Maven convention puts `com.acme.store` under
`src/main/java/com/acme/store` and convention is not always, but the
declaration is what the compiler reads.

Rust peels a `use` from the right until a real file appears, because
`use crate::a::b::C` does not say which of a, b or C is the file. It reads the
crate name and the source root from `Cargo.toml` — including a declared
`[lib] path`, since `src/` is only the default — and knows that Cargo compiles
every direct child of `tests`, `benches` and `examples` as its own crate.

Kotlin reads its type index from the declarations themselves — `class`, `interface`,
`object`, `typealias` and `fun interface` among them — rather than from file
names, because a Kotlin file need not be named after the type
it holds and may declare several. It shares that index with Java: the two
compile to one namespace and import each other freely, so an index of one
extension reports a real edge to the other as a missing type.

In every one of them, an import that names something inside this repository
which is not there is a gap — never a dependency on a published copy of
yourself.

`npx mirofy-cli guide "show an API request with a cache miss"` picks the
diagram type for you if you are not sure which one you want.

**As a CLI you keep** — `npm install -g mirofy-cli`. The command it installs is
**`mirofy`**; the package carries the `-cli` suffix because npm refused the bare
name as too close to the existing `minify`.

**From source** — no install at all, because there is nothing to install:

```bash
git clone https://github.com/Hasan-Laraib/Mirofy.git
node Mirofy/packages/core/bin/mirofy.mjs demo
```

That works on a bare checkout with no `npm install`, because every package here
has zero runtime dependencies.

**As an agent skill** — build the bundle and copy it where your agent looks:

```bash
git clone https://github.com/Hasan-Laraib/Mirofy.git
cd Mirofy && npm install && npm run build:skill

cp -r dist/mirofy ~/.claude/skills/      # Claude Code
cp -r dist/mirofy ~/.agents/skills/      # Codex CLI, opencode
```

Then ask: `Use mirofy to map this repository's runtime architecture.`

The bundle is 2.8 MB and named for the skill inside it — copying `packages/core`
instead installs a skill called `core` that says in its own frontmatter it is
called `mirofy`, and drags the test suite along with it. Before writing the
bundle, `build:skill` copies it somewhere with no repository around it and
renders a diagram: a bundle that only works inside its own checkout is not a
bundle.

Nothing is downloaded at runtime and nothing phones home — there is no update
check, because a tool that reaches the network to tell you about itself is a
tool that reaches the network.

## The pipeline, one step at a time

`mirofy map` is these five steps in order. Run them yourself when you want to
keep an intermediate, or point a step somewhere else:

```bash
npm run scan                    # repository  → evidence graph
npm run model -- --from-graph --graph scan/evidence-graph.json
npm run compile                 # model       → a bounded view
npm run layout                  # view        → positioned document
node packages/core/bin/mirofy.mjs render architecture scan/diagram.json out.html --repo-root .
```

Against **this repository** it records **1,220 facts** across **221 files**,
with **15 gaps** it could not read; derives **18 components and 20
relationships** — every one citing the file and line it came from — and draws
**twelve**, recording what it left out and why.

Those figures are checked, not rem