c4studio 0.3.0__tar.gz → 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {c4studio-0.3.0 → c4studio-0.4.0}/PKG-INFO +224 -7
- {c4studio-0.3.0 → c4studio-0.4.0}/README.md +219 -6
- {c4studio-0.3.0 → c4studio-0.4.0}/pyproject.toml +5 -1
- c4studio-0.4.0/src/c4studio/cli/main.py +890 -0
- c4studio-0.4.0/src/c4studio/diff.py +417 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/generators/json_export.py +15 -2
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/graph/view_graph.py +350 -18
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/icons.py +36 -1
- c4studio-0.4.0/src/c4studio/impact.py +288 -0
- c4studio-0.4.0/src/c4studio/layout_sidecar.py +342 -0
- c4studio-0.4.0/src/c4studio/lint.py +437 -0
- c4studio-0.4.0/src/c4studio/markdown.py +259 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/views.py +8 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/dsl.py +665 -68
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/json_parser.py +2 -0
- c4studio-0.4.0/src/c4studio/publish.py +479 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/render.py +82 -1
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/renderer/diagram-render.mjs +983 -666
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/themes.py +9 -3
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/graph.py +80 -2
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/model_graph.py +3 -0
- c4studio-0.4.0/src/c4studio/webapp/perspectives.py +164 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/server.py +397 -174
- c4studio-0.4.0/src/c4studio/webapp/static/assets/index-BWKhqzG-.js +95 -0
- c4studio-0.4.0/src/c4studio/webapp/static/assets/index-CJj5SYQu.css +1 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/static/index.html +2 -2
- c4studio-0.3.0/src/c4studio/cli/main.py +0 -447
- c4studio-0.3.0/src/c4studio/webapp/static/assets/index-B7IeVhQr.js +0 -80
- c4studio-0.3.0/src/c4studio/webapp/static/assets/index-BosnE_L9.css +0 -1
- {c4studio-0.3.0 → c4studio-0.4.0}/LICENSE +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/__init__.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/__main__.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/cli/__init__.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/diagnostics.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/generators/__init__.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/generators/flowchart.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/generators/mermaid.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/generators/mermaid_common.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/graph/__init__.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/__init__.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/deployment.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/documentation.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/elements.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/enums.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/models/workspace.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/__init__.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/docs.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/expressions.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/implied.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/locations.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/parser/sourcemap.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/py.typed +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/templates/deployment.dsl +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/templates/full-c4.dsl +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/templates/minimal.dsl +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/templates/system-context.dsl +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/templates.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/__init__.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/assistant.py +0 -0
- {c4studio-0.3.0 → c4studio-0.4.0}/src/c4studio/webapp/loader.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: c4studio
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.0
|
|
4
4
|
Summary: Parse Structurizr DSL/JSON and generate C4 diagrams in Mermaid, with a CLI and a React web app
|
|
5
5
|
Keywords: structurizr,c4,architecture,diagrams,dsl
|
|
6
6
|
Author: Geoffrey Koh
|
|
@@ -21,7 +21,11 @@ Requires-Dist: pytest>=8.0 ; extra == 'dev'
|
|
|
21
21
|
Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
|
|
22
22
|
Requires-Dist: anthropic>=1.0 ; extra == 'dev'
|
|
23
23
|
Requires-Python: >=3.13
|
|
24
|
+
Project-URL: Homepage, https://github.com/geoffkoh/c4studio
|
|
24
25
|
Project-URL: Repository, https://github.com/geoffkoh/c4studio
|
|
26
|
+
Project-URL: Documentation, https://github.com/geoffkoh/c4studio/blob/main/docs/dsl-reference.md
|
|
27
|
+
Project-URL: Issues, https://github.com/geoffkoh/c4studio/issues
|
|
28
|
+
Project-URL: Migration guide, https://github.com/geoffkoh/c4studio/blob/main/docs/MIGRATION.md
|
|
25
29
|
Provides-Extra: assistant
|
|
26
30
|
Provides-Extra: dev
|
|
27
31
|
Description-Content-Type: text/markdown
|
|
@@ -57,7 +61,11 @@ Requires Python 3.13+ (uv/uvx can provision it automatically).
|
|
|
57
61
|
- ✅ Mermaid diagram generation — C4 syntax or `flowchart`/`subgraph`
|
|
58
62
|
- ✅ Headless SVG rendering for CI and docs-as-code
|
|
59
63
|
- ✅ Comprehensive type hints
|
|
60
|
-
- ✅
|
|
64
|
+
- ✅ **Perspectives** — annotate elements and relationships with security,
|
|
65
|
+
ownership or anything else, then show one over the diagram
|
|
66
|
+
- ✅ **`c4 lint`** — model standards in CI: orphans, missing descriptions,
|
|
67
|
+
duplicate relationships, styles that match nothing
|
|
68
|
+
- ✅ Custom properties on all elements
|
|
61
69
|
- ✅ Deployment infrastructure modeling
|
|
62
70
|
- ✅ Style and configuration management
|
|
63
71
|
- ⚙️ Optional AI assistant — off by default, and the only feature that
|
|
@@ -90,8 +98,11 @@ uv run c4 webapp samples/ --viewer # read-only, for a kiosk or an embed
|
|
|
90
98
|
|
|
91
99
|
### Editing
|
|
92
100
|
|
|
93
|
-
The
|
|
94
|
-
the diagram
|
|
101
|
+
The source editor is a [CodeMirror 6](https://codemirror.net/) panel that
|
|
102
|
+
opens beside the diagram — from the **Source** button at the right of the
|
|
103
|
+
top bar, the `e` key, the rail on the diagram's right edge, or *Open in
|
|
104
|
+
Source* on any element. The diagram stays put while it opens, and a ● on
|
|
105
|
+
the button marks unsaved work behind a closed editor.
|
|
95
106
|
|
|
96
107
|
- **Syntax highlighting and autocomplete** for DSL keywords, your own element
|
|
97
108
|
identifiers, and view keys — drawn from the loaded workspace, so it knows
|
|
@@ -127,11 +138,12 @@ independent of any curated view — at a selectable abstraction level
|
|
|
127
138
|
(systems / containers / components), with search across every element
|
|
128
139
|
(press `/`), and a details panel showing an element's metadata,
|
|
129
140
|
relationships, the views it appears in (click to jump) and a
|
|
130
|
-
show-definition link
|
|
141
|
+
show-definition link that opens the source editor.
|
|
131
142
|
|
|
132
143
|
The built SPA ships inside the package (`c4studio/webapp/static/`),
|
|
133
144
|
so end users need no Node toolchain. To rebuild the frontend after
|
|
134
|
-
changes (requires Node
|
|
145
|
+
changes (requires Node 20.19+ or 22.12+, what Vite asks for — distinct
|
|
146
|
+
from the Node 18+ that `c4 render` needs at runtime, below):
|
|
135
147
|
|
|
136
148
|
The frontend is an npm workspace: `packages/diagram-core` holds the
|
|
137
149
|
diagram layer (layout, node/edge components, image export) and
|
|
@@ -274,6 +286,211 @@ uv run c4 generate architecture.dsl -f flowchart # flowchart
|
|
|
274
286
|
uv run c4 generate architecture.dsl -f flowchart -o out # one .mmd per view
|
|
275
287
|
```
|
|
276
288
|
|
|
289
|
+
## Perspectives
|
|
290
|
+
A perspective is a named annotation you hang on elements and
|
|
291
|
+
relationships — security, ownership, cost, anything — and then **show over
|
|
292
|
+
the diagram**. What carries it keeps its place and gets a badge with its
|
|
293
|
+
value; everything else fades. The legend follows, listing the values
|
|
294
|
+
rather than the element styles the diagram is no longer painted with.
|
|
295
|
+
|
|
296
|
+
```
|
|
297
|
+
api = container "Payments API" "Authorises and captures." "Python, FastAPI" {
|
|
298
|
+
perspectives {
|
|
299
|
+
"security" "mTLS to the ledger, PCI DSS scope." "High"
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+

|
|
307
|
+
|
|
308
|
+
Colour comes from ordinary styles, matched on the perspective and
|
|
309
|
+
optionally on its value:
|
|
310
|
+
|
|
311
|
+
```
|
|
312
|
+
element "Perspective:security[value==High]" {
|
|
313
|
+
background #2e7d32
|
|
314
|
+
color #ffffff
|
|
315
|
+
}
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
The same overlay is available everywhere the diagram is:
|
|
319
|
+
|
|
320
|
+
```bash
|
|
321
|
+
uv run c4 render architecture.dsl --perspective security -o diagrams/
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
and in the VS Code preview through **C4Studio: Show Perspective…**. A
|
|
325
|
+
perspective carrying a `url` instead of a value has that value **read
|
|
326
|
+
live** — off by default, because the addresses come from the workspace
|
|
327
|
+
file; `c4 webapp --dynamic-perspectives` turns it on.
|
|
328
|
+
|
|
329
|
+
## Publish a site
|
|
330
|
+
Turn the model into something people read without installing anything:
|
|
331
|
+
|
|
332
|
+
```bash
|
|
333
|
+
uv run c4 publish architecture.dsl -o site/
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
Every view becomes its own page — not one page with a switcher, so a link
|
|
337
|
+
to a diagram survives being pasted into a ticket — with the `!docs` prose
|
|
338
|
+
and the ADRs beside them and navigation between. The result is
|
|
339
|
+
**self-contained**: diagrams are inlined SVG and theme icons are embedded
|
|
340
|
+
as `data:` URIs, so it works from a `file://` path, on an air-gapped
|
|
341
|
+
machine, or on any static host.
|
|
342
|
+
|
|
343
|
+
Published diagrams follow the layout you arranged in the Studio
|
|
344
|
+
(`--no-layout` for a fresh one), and `--perspective security` draws the
|
|
345
|
+
whole site through one perspective.
|
|
346
|
+
|
|
347
|
+
To publish on every merge, add the site to a Pages workflow:
|
|
348
|
+
|
|
349
|
+
```yaml
|
|
350
|
+
- uses: actions/checkout@v7
|
|
351
|
+
- uses: actions/setup-node@v6 # c4 render needs Node
|
|
352
|
+
with:
|
|
353
|
+
node-version: "20"
|
|
354
|
+
- run: pipx install c4studio
|
|
355
|
+
- run: c4 publish architecture.dsl -o site/
|
|
356
|
+
- uses: actions/upload-pages-artifact@v4
|
|
357
|
+
with:
|
|
358
|
+
path: site/
|
|
359
|
+
- uses: actions/deploy-pages@v4
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
## What changed (`c4 diff`)
|
|
363
|
+
A pull request that changes the architecture should say what it changed:
|
|
364
|
+
|
|
365
|
+
```bash
|
|
366
|
+
uv run c4 diff architecture.dsl # working tree vs HEAD
|
|
367
|
+
uv run c4 diff architecture.dsl --from main --to HEAD --json
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
Elements and relationships added, removed and changed — and **the views a
|
|
371
|
+
reviewer has to look at again**. A comment-only edit produces nothing,
|
|
372
|
+
which is the signal worth having.
|
|
373
|
+
|
|
374
|
+
Renaming an element that has an alias is reported as a change. Renaming
|
|
375
|
+
one *without* an alias reads as a removal and an addition, because its id
|
|
376
|
+
comes from its name and nothing ties the two together; when a removal and
|
|
377
|
+
an addition share a name, the pair is flagged as a **possible** rename
|
|
378
|
+
rather than assumed. A diff that invents a rename hides a deletion.
|
|
379
|
+
|
|
380
|
+
### On every pull request
|
|
381
|
+
|
|
382
|
+
`c4 diff` needs no Node, so a short workflow can post the answer on each
|
|
383
|
+
pull request that touches the model, updating its own comment on every
|
|
384
|
+
push rather than adding one per push:
|
|
385
|
+
|
|
386
|
+
```yaml
|
|
387
|
+
name: Architecture diff
|
|
388
|
+
|
|
389
|
+
on:
|
|
390
|
+
pull_request:
|
|
391
|
+
paths:
|
|
392
|
+
- "architecture/**"
|
|
393
|
+
|
|
394
|
+
permissions:
|
|
395
|
+
contents: read
|
|
396
|
+
pull-requests: write # to comment
|
|
397
|
+
|
|
398
|
+
jobs:
|
|
399
|
+
diff:
|
|
400
|
+
runs-on: ubuntu-latest
|
|
401
|
+
steps:
|
|
402
|
+
- uses: actions/checkout@v7
|
|
403
|
+
with:
|
|
404
|
+
fetch-depth: 0 # c4 diff reads the base revision from git history
|
|
405
|
+
|
|
406
|
+
- run: pipx install c4studio # no Node needed: diff compares models
|
|
407
|
+
|
|
408
|
+
- name: Diff the model against the target branch
|
|
409
|
+
env:
|
|
410
|
+
BASE: origin/${{ github.base_ref }}
|
|
411
|
+
run: |
|
|
412
|
+
{
|
|
413
|
+
echo "### Architecture changes"
|
|
414
|
+
echo
|
|
415
|
+
echo '```text'
|
|
416
|
+
# A failure is shown rather than failing the job: a workspace
|
|
417
|
+
# the base branch does not have yet cannot be compared.
|
|
418
|
+
c4 diff architecture/workspace.dsl --from "$BASE" --to HEAD 2>&1 \
|
|
419
|
+
|| echo "c4 diff could not compare these revisions (exit $?)"
|
|
420
|
+
echo '```'
|
|
421
|
+
} > architecture-diff.md
|
|
422
|
+
# The job summary works where a comment cannot: a pull request
|
|
423
|
+
# from a fork gets a read-only token.
|
|
424
|
+
cat architecture-diff.md >> "$GITHUB_STEP_SUMMARY"
|
|
425
|
+
|
|
426
|
+
- name: Comment on the pull request
|
|
427
|
+
env:
|
|
428
|
+
GH_TOKEN: ${{ github.token }}
|
|
429
|
+
PR: ${{ github.event.pull_request.number }}
|
|
430
|
+
run: gh pr comment "$PR" --body-file architecture-diff.md --edit-last --create-if-none
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
It reads the base branch from git history, hence `fetch-depth: 0`. A
|
|
434
|
+
workspace the base branch does not have yet cannot be compared, and the
|
|
435
|
+
comment says so instead of failing the job. `--edit-last` edits the
|
|
436
|
+
latest comment made with the workflow's token, so keep this the only
|
|
437
|
+
step that comments with it — or give it a token of its own. Diagrams are
|
|
438
|
+
the action's job (`mode: comment`); this posts the model change, which is
|
|
439
|
+
what a reviewer needs before looking at any of them.
|
|
440
|
+
|
|
441
|
+
## Impact analysis
|
|
442
|
+
What else is involved when one element changes — asked of the model
|
|
443
|
+
rather than of whoever remembers:
|
|
444
|
+
|
|
445
|
+
```bash
|
|
446
|
+
uv run c4 impact architecture.dsl paymentsApi
|
|
447
|
+
uv run c4 impact architecture.dsl paymentsApi --json --depth 2
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
Dependents (what reaches it, and so may break when it changes),
|
|
451
|
+
dependencies (what it reaches, and so may break it), each with how many
|
|
452
|
+
relationships away it is, plus **the views that draw it** — so a change
|
|
453
|
+
advisory board knows which diagrams to open.
|
|
454
|
+
|
|
455
|
+
Containment counts in both directions: a relationship declared against a
|
|
456
|
+
container is one its software system takes part in, which is the same
|
|
457
|
+
rule the views apply when they lift an edge to the nearest visible
|
|
458
|
+
ancestor. An answer that ignored the hierarchy would disagree with the
|
|
459
|
+
diagrams it is about.
|
|
460
|
+
|
|
461
|
+
The same answer is on the Diagrams page: select an element, open its
|
|
462
|
+
details (`i`), and choose **Show impact**. The view repaints — the element
|
|
463
|
+
and whatever contains it marked *Changed*, what depends on it and what it
|
|
464
|
+
depends on in their own colours, the rest faded — and the card gives the
|
|
465
|
+
model-wide counts and how many views draw it. It stays on as you move
|
|
466
|
+
between views; the chip in the toolbar clears it, and choosing a
|
|
467
|
+
perspective replaces it.
|
|
468
|
+
|
|
469
|
+
## Model standards (`c4 lint`)
|
|
470
|
+
Where `c4 check` asks whether a file parses, `c4 lint` asks whether it is
|
|
471
|
+
a good model — the review comments someone would otherwise have to make
|
|
472
|
+
every time:
|
|
473
|
+
|
|
474
|
+
```bash
|
|
475
|
+
uv run c4 lint architecture.dsl
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
Orphaned elements, missing descriptions and technologies, relationships
|
|
479
|
+
declared twice, and styles whose tag nothing carries (invisible
|
|
480
|
+
otherwise, because the legend only lists styles in use). Every finding is
|
|
481
|
+
a warning — a model that breaks a house style still parses and renders —
|
|
482
|
+
so the **exit code** is what gates CI: 1 on any finding, `--exit-zero` to
|
|
483
|
+
report without failing on a model nobody has linted before.
|
|
484
|
+
|
|
485
|
+
Configure it in `c4studio.lint.json` beside the workspace:
|
|
486
|
+
|
|
487
|
+
```json
|
|
488
|
+
{"ignore": ["missing-technology"], "naming": {"container": "^[A-Z]"}}
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
`--json` emits the same shape editors already read, so findings land in
|
|
492
|
+
the Studio's problems list and the VS Code Problems panel.
|
|
493
|
+
|
|
277
494
|
## Headless SVG Rendering
|
|
278
495
|
`c4 render` draws diagrams as standalone SVG with no browser
|
|
279
496
|
and no server — for CI, docs-as-code pipelines and static sites. Layout is
|
|
@@ -361,8 +578,8 @@ code --install-extension c4studio-vscode-*.vsix
|
|
|
361
578
|
```
|
|
362
579
|
|
|
363
580
|
## Documentation
|
|
581
|
+
- **[DSL Reference](./docs/dsl-reference.md)** - **How to write DSL for c4studio**: every construct, the `c4studio.*` extensions, and what is silently ignored. Examples are parsed by the test suite
|
|
364
582
|
- **[DSL Language Support](./docs/dsl-support.md)** - Every keyword in the Structurizr DSL and whether c4studio supports it
|
|
365
|
-
- **[Data Models Reference](./docs/data-models.md)** - Complete guide to all Structurizr models and their fields
|
|
366
583
|
- **[Getting Started](./docs/README.md)** - Workflow and common patterns
|
|
367
584
|
- **[Studio Editor Plan](./docs/studio-editor-plan.md)** - How the editor was designed and built, and the decisions behind it
|
|
368
585
|
- **[Migration Guide](./docs/MIGRATION.md)** - Breaking changes, including the 0.3.0 Studio-by-default flip
|
|
@@ -29,7 +29,11 @@ Requires Python 3.13+ (uv/uvx can provision it automatically).
|
|
|
29
29
|
- ✅ Mermaid diagram generation — C4 syntax or `flowchart`/`subgraph`
|
|
30
30
|
- ✅ Headless SVG rendering for CI and docs-as-code
|
|
31
31
|
- ✅ Comprehensive type hints
|
|
32
|
-
- ✅
|
|
32
|
+
- ✅ **Perspectives** — annotate elements and relationships with security,
|
|
33
|
+
ownership or anything else, then show one over the diagram
|
|
34
|
+
- ✅ **`c4 lint`** — model standards in CI: orphans, missing descriptions,
|
|
35
|
+
duplicate relationships, styles that match nothing
|
|
36
|
+
- ✅ Custom properties on all elements
|
|
33
37
|
- ✅ Deployment infrastructure modeling
|
|
34
38
|
- ✅ Style and configuration management
|
|
35
39
|
- ⚙️ Optional AI assistant — off by default, and the only feature that
|
|
@@ -62,8 +66,11 @@ uv run c4 webapp samples/ --viewer # read-only, for a kiosk or an embed
|
|
|
62
66
|
|
|
63
67
|
### Editing
|
|
64
68
|
|
|
65
|
-
The
|
|
66
|
-
the diagram
|
|
69
|
+
The source editor is a [CodeMirror 6](https://codemirror.net/) panel that
|
|
70
|
+
opens beside the diagram — from the **Source** button at the right of the
|
|
71
|
+
top bar, the `e` key, the rail on the diagram's right edge, or *Open in
|
|
72
|
+
Source* on any element. The diagram stays put while it opens, and a ● on
|
|
73
|
+
the button marks unsaved work behind a closed editor.
|
|
67
74
|
|
|
68
75
|
- **Syntax highlighting and autocomplete** for DSL keywords, your own element
|
|
69
76
|
identifiers, and view keys — drawn from the loaded workspace, so it knows
|
|
@@ -99,11 +106,12 @@ independent of any curated view — at a selectable abstraction level
|
|
|
99
106
|
(systems / containers / components), with search across every element
|
|
100
107
|
(press `/`), and a details panel showing an element's metadata,
|
|
101
108
|
relationships, the views it appears in (click to jump) and a
|
|
102
|
-
show-definition link
|
|
109
|
+
show-definition link that opens the source editor.
|
|
103
110
|
|
|
104
111
|
The built SPA ships inside the package (`c4studio/webapp/static/`),
|
|
105
112
|
so end users need no Node toolchain. To rebuild the frontend after
|
|
106
|
-
changes (requires Node
|
|
113
|
+
changes (requires Node 20.19+ or 22.12+, what Vite asks for — distinct
|
|
114
|
+
from the Node 18+ that `c4 render` needs at runtime, below):
|
|
107
115
|
|
|
108
116
|
The frontend is an npm workspace: `packages/diagram-core` holds the
|
|
109
117
|
diagram layer (layout, node/edge components, image export) and
|
|
@@ -246,6 +254,211 @@ uv run c4 generate architecture.dsl -f flowchart # flowchart
|
|
|
246
254
|
uv run c4 generate architecture.dsl -f flowchart -o out # one .mmd per view
|
|
247
255
|
```
|
|
248
256
|
|
|
257
|
+
## Perspectives
|
|
258
|
+
A perspective is a named annotation you hang on elements and
|
|
259
|
+
relationships — security, ownership, cost, anything — and then **show over
|
|
260
|
+
the diagram**. What carries it keeps its place and gets a badge with its
|
|
261
|
+
value; everything else fades. The legend follows, listing the values
|
|
262
|
+
rather than the element styles the diagram is no longer painted with.
|
|
263
|
+
|
|
264
|
+
```
|
|
265
|
+
api = container "Payments API" "Authorises and captures." "Python, FastAPI" {
|
|
266
|
+
perspectives {
|
|
267
|
+
"security" "mTLS to the ledger, PCI DSS scope." "High"
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+

|
|
275
|
+
|
|
276
|
+
Colour comes from ordinary styles, matched on the perspective and
|
|
277
|
+
optionally on its value:
|
|
278
|
+
|
|
279
|
+
```
|
|
280
|
+
element "Perspective:security[value==High]" {
|
|
281
|
+
background #2e7d32
|
|
282
|
+
color #ffffff
|
|
283
|
+
}
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
The same overlay is available everywhere the diagram is:
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
uv run c4 render architecture.dsl --perspective security -o diagrams/
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
and in the VS Code preview through **C4Studio: Show Perspective…**. A
|
|
293
|
+
perspective carrying a `url` instead of a value has that value **read
|
|
294
|
+
live** — off by default, because the addresses come from the workspace
|
|
295
|
+
file; `c4 webapp --dynamic-perspectives` turns it on.
|
|
296
|
+
|
|
297
|
+
## Publish a site
|
|
298
|
+
Turn the model into something people read without installing anything:
|
|
299
|
+
|
|
300
|
+
```bash
|
|
301
|
+
uv run c4 publish architecture.dsl -o site/
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
Every view becomes its own page — not one page with a switcher, so a link
|
|
305
|
+
to a diagram survives being pasted into a ticket — with the `!docs` prose
|
|
306
|
+
and the ADRs beside them and navigation between. The result is
|
|
307
|
+
**self-contained**: diagrams are inlined SVG and theme icons are embedded
|
|
308
|
+
as `data:` URIs, so it works from a `file://` path, on an air-gapped
|
|
309
|
+
machine, or on any static host.
|
|
310
|
+
|
|
311
|
+
Published diagrams follow the layout you arranged in the Studio
|
|
312
|
+
(`--no-layout` for a fresh one), and `--perspective security` draws the
|
|
313
|
+
whole site through one perspective.
|
|
314
|
+
|
|
315
|
+
To publish on every merge, add the site to a Pages workflow:
|
|
316
|
+
|
|
317
|
+
```yaml
|
|
318
|
+
- uses: actions/checkout@v7
|
|
319
|
+
- uses: actions/setup-node@v6 # c4 render needs Node
|
|
320
|
+
with:
|
|
321
|
+
node-version: "20"
|
|
322
|
+
- run: pipx install c4studio
|
|
323
|
+
- run: c4 publish architecture.dsl -o site/
|
|
324
|
+
- uses: actions/upload-pages-artifact@v4
|
|
325
|
+
with:
|
|
326
|
+
path: site/
|
|
327
|
+
- uses: actions/deploy-pages@v4
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
## What changed (`c4 diff`)
|
|
331
|
+
A pull request that changes the architecture should say what it changed:
|
|
332
|
+
|
|
333
|
+
```bash
|
|
334
|
+
uv run c4 diff architecture.dsl # working tree vs HEAD
|
|
335
|
+
uv run c4 diff architecture.dsl --from main --to HEAD --json
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
Elements and relationships added, removed and changed — and **the views a
|
|
339
|
+
reviewer has to look at again**. A comment-only edit produces nothing,
|
|
340
|
+
which is the signal worth having.
|
|
341
|
+
|
|
342
|
+
Renaming an element that has an alias is reported as a change. Renaming
|
|
343
|
+
one *without* an alias reads as a removal and an addition, because its id
|
|
344
|
+
comes from its name and nothing ties the two together; when a removal and
|
|
345
|
+
an addition share a name, the pair is flagged as a **possible** rename
|
|
346
|
+
rather than assumed. A diff that invents a rename hides a deletion.
|
|
347
|
+
|
|
348
|
+
### On every pull request
|
|
349
|
+
|
|
350
|
+
`c4 diff` needs no Node, so a short workflow can post the answer on each
|
|
351
|
+
pull request that touches the model, updating its own comment on every
|
|
352
|
+
push rather than adding one per push:
|
|
353
|
+
|
|
354
|
+
```yaml
|
|
355
|
+
name: Architecture diff
|
|
356
|
+
|
|
357
|
+
on:
|
|
358
|
+
pull_request:
|
|
359
|
+
paths:
|
|
360
|
+
- "architecture/**"
|
|
361
|
+
|
|
362
|
+
permissions:
|
|
363
|
+
contents: read
|
|
364
|
+
pull-requests: write # to comment
|
|
365
|
+
|
|
366
|
+
jobs:
|
|
367
|
+
diff:
|
|
368
|
+
runs-on: ubuntu-latest
|
|
369
|
+
steps:
|
|
370
|
+
- uses: actions/checkout@v7
|
|
371
|
+
with:
|
|
372
|
+
fetch-depth: 0 # c4 diff reads the base revision from git history
|
|
373
|
+
|
|
374
|
+
- run: pipx install c4studio # no Node needed: diff compares models
|
|
375
|
+
|
|
376
|
+
- name: Diff the model against the target branch
|
|
377
|
+
env:
|
|
378
|
+
BASE: origin/${{ github.base_ref }}
|
|
379
|
+
run: |
|
|
380
|
+
{
|
|
381
|
+
echo "### Architecture changes"
|
|
382
|
+
echo
|
|
383
|
+
echo '```text'
|
|
384
|
+
# A failure is shown rather than failing the job: a workspace
|
|
385
|
+
# the base branch does not have yet cannot be compared.
|
|
386
|
+
c4 diff architecture/workspace.dsl --from "$BASE" --to HEAD 2>&1 \
|
|
387
|
+
|| echo "c4 diff could not compare these revisions (exit $?)"
|
|
388
|
+
echo '```'
|
|
389
|
+
} > architecture-diff.md
|
|
390
|
+
# The job summary works where a comment cannot: a pull request
|
|
391
|
+
# from a fork gets a read-only token.
|
|
392
|
+
cat architecture-diff.md >> "$GITHUB_STEP_SUMMARY"
|
|
393
|
+
|
|
394
|
+
- name: Comment on the pull request
|
|
395
|
+
env:
|
|
396
|
+
GH_TOKEN: ${{ github.token }}
|
|
397
|
+
PR: ${{ github.event.pull_request.number }}
|
|
398
|
+
run: gh pr comment "$PR" --body-file architecture-diff.md --edit-last --create-if-none
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
It reads the base branch from git history, hence `fetch-depth: 0`. A
|
|
402
|
+
workspace the base branch does not have yet cannot be compared, and the
|
|
403
|
+
comment says so instead of failing the job. `--edit-last` edits the
|
|
404
|
+
latest comment made with the workflow's token, so keep this the only
|
|
405
|
+
step that comments with it — or give it a token of its own. Diagrams are
|
|
406
|
+
the action's job (`mode: comment`); this posts the model change, which is
|
|
407
|
+
what a reviewer needs before looking at any of them.
|
|
408
|
+
|
|
409
|
+
## Impact analysis
|
|
410
|
+
What else is involved when one element changes — asked of the model
|
|
411
|
+
rather than of whoever remembers:
|
|
412
|
+
|
|
413
|
+
```bash
|
|
414
|
+
uv run c4 impact architecture.dsl paymentsApi
|
|
415
|
+
uv run c4 impact architecture.dsl paymentsApi --json --depth 2
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
Dependents (what reaches it, and so may break when it changes),
|
|
419
|
+
dependencies (what it reaches, and so may break it), each with how many
|
|
420
|
+
relationships away it is, plus **the views that draw it** — so a change
|
|
421
|
+
advisory board knows which diagrams to open.
|
|
422
|
+
|
|
423
|
+
Containment counts in both directions: a relationship declared against a
|
|
424
|
+
container is one its software system takes part in, which is the same
|
|
425
|
+
rule the views apply when they lift an edge to the nearest visible
|
|
426
|
+
ancestor. An answer that ignored the hierarchy would disagree with the
|
|
427
|
+
diagrams it is about.
|
|
428
|
+
|
|
429
|
+
The same answer is on the Diagrams page: select an element, open its
|
|
430
|
+
details (`i`), and choose **Show impact**. The view repaints — the element
|
|
431
|
+
and whatever contains it marked *Changed*, what depends on it and what it
|
|
432
|
+
depends on in their own colours, the rest faded — and the card gives the
|
|
433
|
+
model-wide counts and how many views draw it. It stays on as you move
|
|
434
|
+
between views; the chip in the toolbar clears it, and choosing a
|
|
435
|
+
perspective replaces it.
|
|
436
|
+
|
|
437
|
+
## Model standards (`c4 lint`)
|
|
438
|
+
Where `c4 check` asks whether a file parses, `c4 lint` asks whether it is
|
|
439
|
+
a good model — the review comments someone would otherwise have to make
|
|
440
|
+
every time:
|
|
441
|
+
|
|
442
|
+
```bash
|
|
443
|
+
uv run c4 lint architecture.dsl
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
Orphaned elements, missing descriptions and technologies, relationships
|
|
447
|
+
declared twice, and styles whose tag nothing carries (invisible
|
|
448
|
+
otherwise, because the legend only lists styles in use). Every finding is
|
|
449
|
+
a warning — a model that breaks a house style still parses and renders —
|
|
450
|
+
so the **exit code** is what gates CI: 1 on any finding, `--exit-zero` to
|
|
451
|
+
report without failing on a model nobody has linted before.
|
|
452
|
+
|
|
453
|
+
Configure it in `c4studio.lint.json` beside the workspace:
|
|
454
|
+
|
|
455
|
+
```json
|
|
456
|
+
{"ignore": ["missing-technology"], "naming": {"container": "^[A-Z]"}}
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
`--json` emits the same shape editors already read, so findings land in
|
|
460
|
+
the Studio's problems list and the VS Code Problems panel.
|
|
461
|
+
|
|
249
462
|
## Headless SVG Rendering
|
|
250
463
|
`c4 render` draws diagrams as standalone SVG with no browser
|
|
251
464
|
and no server — for CI, docs-as-code pipelines and static sites. Layout is
|
|
@@ -333,8 +546,8 @@ code --install-extension c4studio-vscode-*.vsix
|
|
|
333
546
|
```
|
|
334
547
|
|
|
335
548
|
## Documentation
|
|
549
|
+
- **[DSL Reference](./docs/dsl-reference.md)** - **How to write DSL for c4studio**: every construct, the `c4studio.*` extensions, and what is silently ignored. Examples are parsed by the test suite
|
|
336
550
|
- **[DSL Language Support](./docs/dsl-support.md)** - Every keyword in the Structurizr DSL and whether c4studio supports it
|
|
337
|
-
- **[Data Models Reference](./docs/data-models.md)** - Complete guide to all Structurizr models and their fields
|
|
338
551
|
- **[Getting Started](./docs/README.md)** - Workflow and common patterns
|
|
339
552
|
- **[Studio Editor Plan](./docs/studio-editor-plan.md)** - How the editor was designed and built, and the decisions behind it
|
|
340
553
|
- **[Migration Guide](./docs/MIGRATION.md)** - Breaking changes, including the 0.3.0 Studio-by-default flip
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
# project. C4 is the notation, not a vendor's product, so the name stays
|
|
5
5
|
# honest even if support broadens beyond Structurizr DSL.
|
|
6
6
|
name = "c4studio"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.4.0"
|
|
8
8
|
description = "Parse Structurizr DSL/JSON and generate C4 diagrams in Mermaid, with a CLI and a React web app"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "MIT"
|
|
@@ -28,7 +28,11 @@ dependencies = [
|
|
|
28
28
|
]
|
|
29
29
|
|
|
30
30
|
[project.urls]
|
|
31
|
+
Homepage = "https://github.com/geoffkoh/c4studio"
|
|
31
32
|
Repository = "https://github.com/geoffkoh/c4studio"
|
|
33
|
+
Documentation = "https://github.com/geoffkoh/c4studio/blob/main/docs/dsl-reference.md"
|
|
34
|
+
Issues = "https://github.com/geoffkoh/c4studio/issues"
|
|
35
|
+
"Migration guide" = "https://github.com/geoffkoh/c4studio/blob/main/docs/MIGRATION.md"
|
|
32
36
|
|
|
33
37
|
[project.optional-dependencies]
|
|
34
38
|
# The assistant is the one feature that leaves the machine, and the only
|