How-to guides › Use the Arche app

How-to guides

The Arche app on .arche sources

The Arche app is the visual editor: the canvas, the specification pages, the scenarios, the stories and the Code page. archec app serves it on a project written in arche-lang. You edit in the app, and your changes go back into the .arche files. In VS Code, Arche: Open Arche App does the same from the editor.

A first run#

In a folder with a main.arche (the one from How arche-lang maps to Arche will do):

archec app main.arche
✓ the Arche app on main.arche: http://127.0.0.1:8080/
  9 YAML files built from 1 .arche files; saves are written back into the .arche files

Open the address in a browser. Stop the server with Ctrl+C. To choose the port and let the app run the project's Python:

archec app main.arche --port 9000 --allow-python

How it works#

The project stays in its .arche files. There is no YAML on disk.

What the app reads#

The app reads Arche YAML. archec builds it from the sources, as archec build does: every model, catalog and specification file the app asks for is the emitter's output. It is built again when a source changes: in the editor, on disk, or after a git pull.

What the app saves#

A save is written back into the sources. archec compares what it gave the app with what the app sends back. Each difference becomes the smallest edit of the source that gives it:

In the app In the .arche source
a name, a text, a number, a position changed the label or the property value replaced in place ("Brake" → "Disc brake", at 300, 40 → at 320, 40)
a list of names changed the property written again (languages fr, en, de)
a component, port, link, requirement… added its declaration, as archec import writes it, beside its siblings
an element removed its declaration deleted
a field the language has no word for attr key = value on the declaration it belongs to
a file the project did not have (problems.yaml) data "problems.yaml" = {…} in app/problems.arche, included from the main file

Every save is checked before anything is written:

  1. The edited sources are built in memory and emitted again.
  2. The save is accepted only when the file comes out exactly as the app sent it, and the model has no new errors.
  3. Otherwise the app gets an HTTP 422 answer with the differences that remain. The sources are left as they were.

The text panes show arche-lang#

Some panes of the app showed YAML: the pane beside the canvas, and the YAML mode of the specification pages (now called arche). They now show the .arche declaration behind what is on screen. That is the selected component, the requirement the form shows, or the file a document is written from (a list picks among them).

Saving the pane (Ctrl+S) replaces that text in its file. It is checked the same way. A change that would leave the model with errors is refused, and the errors are marked on their lines.

In VS Code#

Arche: Open Arche App starts the server inside the extension, on the workspace's model, and opens it. arche.app.openIn chooses where: your browser, or a VS Code tab.

  • The app reads the model as the editor has it, unsaved text included.
  • A save from the app is applied as one edit of the .arche files. Ctrl+Z undoes it. It is saved to disk when the file had no unsaved changes of its own.
  • A status bar item shows that the server is running. Arche: Stop Arche App stops it.
  • The server listens on 127.0.0.1 only, with a token in the URL it opens. Other programs on the machine cannot use it.
Setting
arche.app.openIn browser (default) or editor
arche.app.port the port; 0 (default) picks a free one
arche.app.allowPython let the app run the project's Python (with your privileges)
arche.app.allowBuild let the Code page build the source and run language servers

What it serves#

The server is the Arche app's own server, rewritten in TypeScript in src/app/ (the original is in Go). It has the same routes, request and answer shapes, status codes and messages, so the app runs unchanged.

Routes Module Notes
models, files, catalogs (/api/models, /api/files, /api/layout, /api/types, …), versions server.ts, project.ts, writeback.ts YAML built from the sources and written back into them; the If-Match/ETag versions work as before
/api/arche/source, /api/arche/language source.ts new: the .arche text behind what the app shows
datasheets, images, organigram, pptx templates, presentations stores.ts real files, in the project folder (or the folder an assets entry copies)
/api/source/* sources.ts, sourceindex.ts, sourcedeps.ts, sourcewrite.ts the code under the project's source-root
/api/git/* git.ts the git command line
/api/python/*, /api/code/* python.ts, codetools.ts only with --allow-python, --allow-build
presence, user and Arche configuration server.ts ~/.arche/config (theme, read-only) and .arche/config.yaml (git rights) stay YAML: they are settings, not the project

Read-only mode (readOnly: true in ~/.arche/config) refuses every write, as the Go server did.

archec app --source-index prints the index of the project's code as JSON, and exits. It prints what the Go server's --source-index printed. Use it for the model/code checks of a CI job. It needs a source-root in the project block (source-root "code/firmware").

Options#

Option
--port 8080, --host 127.0.0.1 where it listens
--static <dir> the built app (by default: beside archec, or ../arche/frontend/dist)
--allow-python [--python python3] the Python runtime
--allow-build builds and language servers
--token <t> answer only requests carrying it (?token= once, then a cookie)
--source-index print the code index and exit

Limits#

  • The SSH terminal (/api/terminal/ssh) is not served. Use a terminal of your editor.
  • --source-index stops with an error when the project block has no source-root.