jarvis-at-skic
e149131307
Build and publish Eldorado documentation / build (pull_request) Successful in 39s
49 lines
4.2 KiB
Markdown
49 lines
4.2 KiB
Markdown
---
|
|
title: Archify diagrams
|
|
description: Author typed JSON diagrams and embed their local interactive viewer in documentation.
|
|
---
|
|
|
|
## Capabilities
|
|
|
|
[Archify](https://github.com/tt-a1i/archify) 3.0.1 is vendored at commit `d5a1333d7447c866a765adac7d4d062f2f02e4d2` under `vendor/archify/`, with its MIT license and third-party notices preserved.
|
|
|
|
| Diagram type | Intended use |
|
|
| --- | --- |
|
|
| Architecture | Components, boundaries and relationships; also used for the organization structure views |
|
|
| Workflow | Processes, branches and approval gates |
|
|
| Sequence | Participants and ordered messages |
|
|
| Dataflow | Sources, processing and destinations |
|
|
| Lifecycle | States and transitions |
|
|
|
|
The standalone viewer provides pan/zoom, node inspection, search/focus, relationship tracing, light/dark themes, and an export menu. Motion is opt-in. The Organization views exercise architecture mode; Roadmap uses native Workflow v2 with a horizontal desktop path and the same stages stacked on mobile. Other diagram types use the same build interface but do not yet have portal-specific examples. Browser-dependent exports such as video are not acceptance-tested by this integration.
|
|
|
|
## Author a diagram
|
|
|
|
Create `diagrams/<name>.<type>.json` using the matching schema and authoring guidance in `vendor/archify/schemas/` and `vendor/archify/references/`. Use stable IDs, explicit relationships, and honest evidence labels. Do not include private information merely because the source repository is private: Pages access is a separate platform policy.
|
|
|
|
Set `meta.output` to `static/diagrams/<name>/index.html`. The build validates the typed source with the upstream showcase profile, renders locally, checks the artifact, and publishes the standalone HTML. Editable JSON stays in the repository; the portal does not publish source-download files.
|
|
|
|
Roadmap has a scoped multiline typography adapter in `scripts/roadmap-viewer.mjs`. Its two `.workflow.json` sources use the native v2 schema, one lane, `mainPath`, logical columns and native routes. The native renderer validates the schema and solves geometry; the adapter wraps the existing action/output/exit copy, removes the redundant lane frame and trims empty canvas. The final artifact then passes the upstream showcase composition checker. This path records source, adapter and final artifact hashes in private `.cache/archify/*.portal.json` receipts, not upstream `deliver` provenance. Keep the vendor unchanged and run the Roadmap browser check at 1440, 390 and 320 pixels after any copy or sizing change. Typography is embedded in the SVG so exports retain it.
|
|
|
|
```sh
|
|
pnpm diagrams:build
|
|
pnpm test
|
|
pnpm build
|
|
```
|
|
|
|
## Embed it in MDX
|
|
|
|
```mdx
|
|
import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
|
|
|
|
<ArchifyDiagram name="organization-structure" title="Eldorado organization structure" />
|
|
```
|
|
|
|
Supply a text alternative below each diagram. The wrapper uses a local, base-path-aware iframe with a descriptive title, scripts and downloads enabled, and no same-origin or parent-navigation permissions. The top-right expand icon expands the diagram in a full-screen modal on the current page, with the same iframe sandbox. Close it with the Close button or Escape; focus returns to the opener. It does not open a new tab. The separate standalone HTML asset remains directly addressable and is not itself iframe-sandboxed, so publish only reviewed, trusted diagrams. Generated output is ignored by Git and rebuilt in CI.
|
|
|
|
## Integration boundaries
|
|
|
|
The portal remains Docusaurus/React/TypeScript with pnpm. It uses the actual upstream renderer, not a look-alike diagram implementation. No Astro site, global agent installation, hosted rendering service, or AI API was added. The integration disables Archify update networking and does not run its installation commands. This does not disable every possible build-time request: upstream can fetch authored, digest-pinned brand URLs. The current example contains none. Review external asset sources deliberately; update-check suppression is not an offline guarantee.
|
|
|
|
Upgrades are deliberate: review the upstream diff and licenses, update the provenance record and vendor checksums, then run tests, diagram validation, production build, and browser checks. Do not edit upstream files for portal styling.
|