ArchiCode

Streamline architectural design and visualization with an as-code approach. Integrates C4 Model and ArchiMate for efficient workflow.

Run

The following commands assume the ArchiCode workspace is located in the current directory. The workspace file is .archicode.yaml, a hidden file (ls -a lists it). It was called workspace.yaml before 0.18: rename it with git mv workspace.yaml .archicode.yaml, or pass -w workspace.yaml. The commands print this advice when they find workspace.yaml and no .archicode.yaml; the manual says more (section Upgrading).

Show the help information

docker run \
  -u "$(id -u):$(id -g)" \
  -v "$(pwd):/workdir" -w "/workdir" \
  --rm ghcr.io/tmorin/archicode --help

Generate all views

docker run \
  -u "$(id -u):$(id -g)" \
  -v "$(pwd):/workdir" -w "/workdir" \
  --rm ghcr.io/tmorin/archicode views generate

Compare two plateaus

A workspace can have states, the plateaus, each a layer over another one: the manifests that say plateau: <id> in their header, and a manifest of kind archicode.morin.io/plateau that lists what the layer changes. diff tells what is new, changed and removed in a plateau, compared with the plateau it overrides, and what moved, was split or merged when an element says what it replaces; --against names another plateau to compare with, and views generate draws the comparison next to the views, and diff --fail-on removed,moved exits with the code 3 when the comparison holds a change of one of the listed states, to fail a build; diff --width 100 wraps the text table to 100 columns. See "Plateaus" in the manual.

docker run \
  -u "$(id -u):$(id -g)" \
  -v "$(pwd):/workdir" -w "/workdir" \
  --rm ghcr.io/tmorin/archicode diff

docker run \
  -u "$(id -u):$(id -g)" \
  -v "$(pwd):/workdir" -w "/workdir" \
  --rm ghcr.io/tmorin/archicode views generate --against baseline

Get the JSON schema for the Workspace resource

docker run \
  -u "$(id -u):$(id -g)" \
  -v "$(pwd):/workdir" -w "/workdir" \
  --rm ghcr.io/tmorin/archicode query schemas workspace

Get the JSON schema for the Manifest resource

docker run \
  -u "$(id -u):$(id -g)" \
  -v "$(pwd):/workdir" -w "/workdir" \
  --rm ghcr.io/tmorin/archicode query schemas manifest

Open the editor on the workspace folder

docker run \
  -u "$(id -u):$(id -g)" \
  -v "$(pwd):/workdir" -w "/workdir" \
  -p 127.0.0.1:48080:48080 \
  --rm ghcr.io/tmorin/archicode editor serve

The command prints a URL, http://127.0.0.1:48080/?token=...: opening it in a browser serves the editor and opens the folder of .archicode.yaml in it, with nothing to pick (the page is refused without the token; the editor removes it from the address bar, and a session cookie lets a reload in): browse the elements, edit them, see their diagrams and the maps of the application and technology layers, and save. It works in any browser. The same editor is published next to the manual, at https://tmorin.github.io/archicode/editor/, and is a single file (standalone.html): opened from there, or from a file, it asks for a folder instead, which needs the File System Access API (Chrome, Edge, Brave, Opera).

The server writes to the folder, so it does not trust the network: the page and every call carry a token that only the printed URL gives, a request must be addressed to localhost, 127.0.0.1 or [::1] (--allowed-host <name> adds one, for a server reached by name), a page of another origin is refused, and the editor can only reach the .yaml, .yml and .json files below the folder of .archicode.yaml, never another hidden entry or a link that leaves it. The container listens on 0.0.0.0 so that Docker's -p forwards traffic: keep the host side of the mapping on 127.0.0.1 as above, since -p 48080:48080 would expose the port to the whole LAN. The workspace file must be named .archicode.yaml; --workspace points at one in another folder:

docker run \
  -u "$(id -u):$(id -g)" \
  -v "$(pwd):/workdir" -w "/workdir" \
  -p 127.0.0.1:48080:48080 \
  --rm ghcr.io/tmorin/archicode \
  --workspace ./architecture/.archicode.yaml editor serve

The same works directly against a locally built jar, with no Docker and no port mapping to reason about:

./mvnw package -Dquarkus.container-image.build=false -Dmaven.test.skip
java -jar target/quarkus-app/quarkus-run.jar \
  --workspace "$(pwd)/.custom/.archicode.yaml" \
  editor serve --host 127.0.0.1 --port 48080

Editor sources

The editor page src/main/resources/editor-webapp/standalone.html is generated: do not edit it. Edit the parts in src/main/editor/ (six layer folders, core to composition, in the order of layers.json), then run npm run editor:build and commit the page with the parts. npm run format formats the parts, npm run editor:check checks the page is the assembly of the parts and the layer rules. CLAUDE.md tells the rest.

Maintenance

Dependencies upgrade

./mvnw versions:display-dependency-updates

Quarkus update

./mvnw quarkus:update

Release

./mvnw --batch-mode release:clean \
&& ./mvnw --batch-mode release:prepare \
  -DreleaseVersion=X.Y.Z \
  -DdevelopmentVersion=Y.X.Z-SNAPSHOT

Build package and OIC image

./mvnw package -Dquarkus.container-image.build=true

Build package and OIC image without test execution

./mvnw package -Dquarkus.container-image.build=true -Dmaven.test.skip

./mvnw clean package -Dquarkus.container-image.build=true