Query Archi models on demand.

# Overview

One HTTP call, one isolated Archi run.

flowchart LR
  client(["API client"]) -->|"POST /api/run"| server["archi-server"]
  client -->|"repo CRUD + sync"| server
  server -->|"spawn"| archi["Archi ACLI (jArchi + coArchi)"]
  archi -->|"stdout + resultFile"| server
  server -->|"JSON"| client

  subgraph volumes ["Mounted volumes"]
    direction TB
    scripts["/scripts - script repos (git)"]
    models["/models - model repos + archimate files"]
  end
  server -.->|"clone / fetch / pull"| scripts
  server -.->|"clone / fetch / pull"| models
      

# Quickstart

Fetch the binaries, build once, run anywhere.

1. Fetch Archi and coArchi

# downloads into vendor/ (git-ignored)
scripts/fetch-archi.sh

jArchi's binary is not publicly downloadable. Drop the provided *.archiplugin into vendor/plugins/, set JARCHI_URL, or build it from source (see below).

2. Build and run with Docker Compose

docker compose up --build

3. Call the API

curl -s http://localhost:3000/api/run \
  -H 'content-type: application/json' \
  -d '{
    "correlationId": "demo-1",
    "model": "my-model",
    "script": "archiServer.setResult({ elements: $(\".archimate-element\").size() });"
  }'

# API

Run a script, or manage the git repos behind it.

Request

{
  "correlationId": "string",
  "script":        "jArchi script source",
  "model":         "path inside the /models volume"
}

Response

{
  "correlationId": "demo-1",
  "stdout":        "...",
  "stderr":        "...",
  "exitCode":      0,
  "result": {
    "file":      "/var/archi/runs/run-xxxx/result.json",
    "encoding":  "json",
    "content":   { "any": "parsed JSON, text, or base64" },
    "size":      42,
    "truncated": false
  }
}

result is null when a script does not advertise a result file. A run that exceeds the timeout returns 504 with the same shape.

Export views to Markdown + Mermaid

curl -s http://localhost:3000/api/export/mermaid \
  -H 'content-type: application/json' \
  -d '{
    "correlationId": "export-1",
    "model": "my-model",
    "view": "Customer Journey",
    "direction": "LR"
  }'

Omit view and folder to export all views. The response adds a top-level markdown field; 404 means the model is missing or no view matched.

Result convention

A script advertises a result file by printing a JSON object with a resultFile key (aliases: result_file, result). Relative paths resolve against the run directory.

Every script gets a small prelude:

archiServer = {
  correlationId: "demo-1",
  runDir:        "/var/archi/runs/run-xxxx",
  resultFile:    "/var/archi/runs/run-xxxx/result.json",
  // writes result.json and prints { "resultFile": ... }
  setResult: function (value) { /* ... */ }
};

sequenceDiagram
  autonumber
  participant C as Client
  participant S as archi-server
  participant A as Archi ACLI
  C->>S: POST /api/run
  S->>S: validate + acquire semaphore
  S->>S: write script.ajs (+ prelude)
  S->>A: runScript on --loadModel / --modelrepository.loadModel
  A-->>S: stdout, stderr, exit code
  A->>S: resultFile printed to stdout
  S->>S: read + decode result file
  S-->>C: 200 {correlationId, stdout, stderr, exitCode, result}
      

# Repositories

Models and scripts are git-managed sub-folders of the mounted volumes. Add over HTTPS with an access token, sync, and remove by id.

flowchart LR
  add["POST /api/models clone url"] --> ready["/models/{id} git repo"]
  ready --> run["POST /api/run model = id"]
  ready --> sync["POST /api/models/:id/sync fetch + ff-only"]
  sync --> ready
  ready --> del["DELETE /api/models/:id"]
      

Add a repository

curl -s http://localhost:3000/api/models \
  -H 'content-type: application/json' \
  -d '{
    "url": "https://git.example.com/org/my-model.git",
    "id": "my-model",
    "branch": "main",
    "username": "oauth2",
    "token": "glpat-xxxxxxxx"
  }'

Returns 201 with the repository object, or 409 if the id exists:

{
  "id":      "my-model",
  "kind":    "model",
  "path":    "/models/my-model",
  "url":     "https://git.example.com/org/my-model.git",
  "branch":  "main",
  "commit":  "7fd1a60b01f9",
  "subject": "Merge pull request #6",
  "date":    "2012-03-06T15:06:50-08:00",
  "dirty":   false
}

Sync & remove

• POST /:id/sync: git fetch --prune then a fast-forward-only merge. Returns the object plus updated and previousCommit. Non-fast-forward local commits are refused.
• DELETE /:id: deletes the folder and returns 204.

# Configuration

Everything is environment driven.

# Plugins

Why these exact versions, and how to build jArchi yourself.

Build jArchi from source

# requires git + maven; compiles tag v1.11.0 against the local Archi install
scripts/build-plugins.sh

• Publishes the Archi install as a p2 repository used as the Tycho target platform.
• Produces vendor/plugins/com.archimatetool.script*.jar.

# Notes & limitations

• Each run starts a fresh JVM. Keep ARCHI_MAX_CONCURRENCY low.
• The image runs as non-root user archi (uid 1001, override with --build-arg ARCHI_UID=$(id -u)). /models and /scripts must be writable by that uid so repositories can be cloned and synced.
• Repository auth is HTTPS + access token only (no SSH). Tokens live under <repo>/.git/ with mode 0600.
• CI typechecks and runs the unit tests on every push and PR; the image is published to GHCR only on v* tag commits.
• Directory models must already be coArchi/GRAFICO repositories (contain model/folder.xml); otherwise coArchi reports an error in stderr.
• Archi writes a harmless SLF4J(W): No SLF4J providers were found. line to stderr. Silence it with JAVA_TOOL_OPTIONS=-Dslf4j.internal.verbosity=ERROR if desired.