Configuration

Configuration

The first of these is used: the file given with --config (TOML or JSON); system-diff.toml at the repository root (as it is in the commit being read, else on disk); [tool.system-diff] in pyproject.toml. Every key is optional, and a table you give merges key by key over the defaults.

tests  = ["tests/**", "web/src/**/*.test.ts"]   # test files: not parts; a change without one is a test-gap
deploy = ["Dockerfile", "deploy/**"]            # a change to these is a deployment change
compose = "docker-compose.yml"                  # its services are the deployed containers
config_files = ["docker-compose*.yml", ".env.*example", "deploy/*.env"]   # deploy configuration (see externals)

[code]
roots = ["app/", "web/src/"]        # where code lives (default: the whole repository)
extensions = [".py", ".ts", ".tsx"] # default .py .ts .tsx .js .jsx
skip = ["node_modules", "dist"]     # folder names never read (* allowed)
aliases = { "@/" = "web/src/" }     # import prefixes, as in tsconfig paths
python_paths = ["", "src/"]         # where `import a.b` is looked up
group = { default = 2, web = 3 }    # an undeclared part is named by its first N path segments (per top folder)

[[components]]                      # a part: the first whose paths match a file owns it
id = "api"
label = "API"
kind = "interface"                  # the column: ui | interface | logic | data
layer = "new"                       # optional: new (blue band) | legacy (dashed) | shared
container = "backend"               # optional: where it is deployed
paths = ["app/api/**"]              # * stays within a folder, ** crosses folders
hub = false                         # true: used everywhere, drawn without the arrows into it
quiet = false                       # true: drawn without arrows

[[externals]]                       # an outside system, known by the settings code reads
id = "postgres"
label = "PostgreSQL"
shape = "db"                        # db: drawn with stored data; otherwise outside the system
env = ["DATABASE_URL", "PG*"]

[[api]]                             # who serves a URL the front end calls ("/api/…" strings)
prefix = "/api/"
component = "api"

[containers]                        # container -> label
backend = "Backend"

[internal_env]                      # a setting that points one part at a container
BACKEND_URL = "backend"

[migrations]
glob = "db/migrations/*.sql"
schemas = [[1, 99, "public"]]       # migration number ranges -> schema of unqualified tables
store = "postgres"                  # the external the tables live in

[picture]
columns = [["ui", "What people use"], ["interface", "Entry points"], ["logic", "Logic"],
           ["data", "Data access"], ["store", "Stored data"], ["external", "Outside the system"]]
ui_containers = ["web"]             # parts deployed here are what people use
main_containers = []                # containers not named on their parts' boxes
min_flow = 1                        # import sites before a connection is drawn
top_flows = 2                       # connections drawn from each part, strongest first
max_ext_edges = 1                   # users drawn per outside system; its box counts the rest
hub_note = "used across the code"
legend = { new = "new", legacy = "legacy, still running", undeclared = "not named in system-diff.toml" }

[readme]
file = "README.md"
image = "docs/diagrams/system.svg"
begin = "<!-- system-map:begin -->"
end = "<!-- system-map:end -->"
how = "…"                           # the "How this map is made" text; {dormant} is where the not-drawn note goes
stale = "…"                         # the warning for --stale; {pictures} and {it}
dormant = "…"                       # {names}

[narrate]
settings = ["~/.claude/settings.team.json"]   # more Claude Code settings files, highest precedence last

The templates are Python format strings: write {{ and }} for a literal brace.

When is an outside system drawn?

When code reads one of its env settings and a deploy configuration (config_files) sets one of them. When code reads it but no deploy file sets it, it is dormant: listed in system.json and named under the README map, but not drawn. A setting nobody deploys is usually residue, and drawing it would claim a connection the running system does not have.