Metadata-Version: 2.5
Name: system-diff
Version: 0.1.0
Summary: Draws your system from its code (parts, entry points, data, outside systems) and what each change adds, changes or removes. No dependencies; SVG pictures for PRs and READMEs.
Project-URL: Homepage, https://github.com/simplifiedmachine/system-diff
Project-URL: Documentation, https://github.com/simplifiedmachine/system-diff/wiki
Project-URL: Issues, https://github.com/simplifiedmachine/system-diff/issues
Author: simplifiedmachine
License-Expression: MIT
License-File: LICENSE
Keywords: architecture,code-review,code-visualization,developer-tools,diagrams,pull-requests,system-design
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: mcp>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.10; extra == 'mcp'
Provides-Extra: png
Requires-Dist: playwright>=1.40; extra == 'png'
Description-Content-Type: text/markdown

# system-diff

Draws your system from its code (parts, entry points, data, outside systems) and what each change adds, changes or
removes. No dependencies; SVG pictures for PRs and READMEs.

<!-- system-map:begin -->
![System map, generated from the code](https://raw.githubusercontent.com/simplifiedmachine/system-diff/main/docs/diagrams/system.svg)

<details><summary>How this map is made</summary>

Regenerated by `system-diff` from the code: the parts and their columns from `system-diff.toml`, the connections from imports, API calls and the settings each part reads, the outside systems from the settings a deploy configuration sets, and the tables from the migrations. Parts used everywhere are drawn without the arrows into them, and each part keeps only its strongest connections; `system-diff map` writes all of them to `system.json`.

Read by the code but set by no deploy configuration, so not drawn: Headless Chromium (Docker or Playwright) (png).

</details>
<!-- system-map:end -->

## What it does

- **`map`**: reads a commit straight from git (no checkout) or a folder, and writes `system.json` (everything it
  found) and `system.svg` (the picture): a column per role, from what people use through entry points, logic and data
  access to stored data and outside systems.
- **`diff`**: the typed difference between two commits, or a commit and your working tree: parts, endpoints,
  connections, outside systems, tables, settings and deployment files added, changed or removed. One sentence
  (`headline.txt`), the exact list (`plan.txt`, like `terraform plan`), and a picture of only what changed, with the
  parts it touches beside it (`diff.svg`). `--narrate` adds a plain-words summary from your own LLM.
- **`readme`**: keeps a generated system map in your README, between two markers.
- **`draw`**: hand-made pictures in the same look, from small JSON specs: maps, stages of a process, sequences.

Deterministic: the same code gives the same picture, byte for byte, and a part that did not change keeps its place.

## Install

```sh
pipx install system-diff
```

Python 3.11 or newer, nothing else. `pip install "system-diff[png]"` adds PNG output through Playwright; `system-diff
png` also uses Docker when it is there.

## Use

```sh
system-diff map --dir . --out docs/diagrams          # the system as it is now
system-diff diff --base origin/main --out out        # what this branch does to it
system-diff diff --base HEAD --head . --out out      # what your uncommitted work does to it
system-diff readme --json docs/diagrams/system.json  # refresh the map in README.md
```

With no config, every folder of code is a part named by its path. A `system-diff.toml` at the repository root names the
parts and says what is what:

```toml
tests = ["tests/**"]

[code]
roots = ["app/", "web/src/"]

[[components]]
id = "api"
label = "API"
kind = "interface"          # ui | interface | logic | data: the column it is drawn in
paths = ["app/api/**"]

[[externals]]
id = "postgres"
label = "PostgreSQL"
shape = "db"
env = ["DATABASE_URL"]      # the settings that reach it
```

Every key, and how the code is read: [the wiki](https://github.com/simplifiedmachine/system-diff/wiki).

## In pull requests

This repository runs system-diff on itself: the map above is regenerated from its own code, CI fails when it is out of
date, and every pull request gets its system diff as a comment (`.github/workflows/system-diff.yml`, which you can
copy).

## With AI coding agents

When an agent changes the code with you, the question is what it did to the system. system-diff answers it as you go:

```sh
pipx install system-diff
pipx inject system-diff mcp  # the MCP server's one dependency
system-diff setup claude     # the hook, a skill and the MCP server, in one step (--scope project, --undo)
system-diff watch            # http://127.0.0.1:8765/ : the system diff since you last marked it seen
```

- **After every Claude Code turn**, one line says what changed in the system since your checkpoint ("Adds 1 endpoint
  (DELETE /api/orders/{id}); changes 1 table (public.orders)."), or nothing when nothing structural did.
- **The live page** redraws as files change. Press **Mark as seen** once you have understood it: the next diff then
  shows only what is new to you. `system-diff checkpoint` does the same from the terminal.
- **The MCP server** gives the agent `system_diff` (the exact plan to explain from, and the picture), `system_map`,
  `draw` (pictures of processes and sequences in the same look) and `checkpoint`.
- The working tree is read as a snapshot (untracked files included) without touching your index, HEAD or branches,
  and the checkpoint lives under `refs/system-diff/`, in your clone only.

## License

MIT
