This page is for people working on Plaid itself. If you only want to run Plaid, download plaid.jar from the releases page and follow the Quick Start instead. You do not need any of the tooling below.

1. Ports

Plaid listens on 8080 by default. Everything in the documentation assumes that port.

The one exception is the development server (clojure -X:dev), which listens on 8085 so that it does not collide with a release jar running on the same machine. That override lives in plaid-core/resources/config.dev.toml and is never written to data/config.toml.

To change the port a release jar uses, edit [server] port in data/config.toml (written automatically on first launch) and restart:

[server]
port = 9090

2. Repository Layout

Plaid is a monorepo:

plaid-core/

The Clojure server: REST API, data model, storage, audit log, query engine. Also holds this documentation under docs/.

plaid-ud/

The bundled Universal Dependencies editor (a Vite/React SPA), served from the jar at /ud/.

plaid-igt/

The bundled interlinear glossed text editor (a Vite SPA), served from the jar at /igt/.

plaid-dict/

The bundled dictionary reader (a Vite/React SPA), served from the jar at /dict/.

plaid-umr/

The bundled Uniform Meaning Representation editor (a Vite/React SPA), served from the jar at /umr/.

plaid-ui/

The component and helper package the four SPAs share. Not published: each app resolves it from the checkout.

plaid-agent/

The Python assistants for UD, IGT and UMR, one distribution named larc-plaid-agent. Installed from a checkout, not published.

plaid-client-js/

The official JavaScript client, published to npm as @larc-iu/plaid-client.

plaid-client-py/

The official Python client, published to PyPI as larc-plaid-client.

examples/

Small standalone demos built against the clients.

bb/, bb.edn

The babashka task runner that drives builds, tests, and releases.

3. Building From Source

Builds are driven by babashka tasks defined in bb.edn, which reproduce the GitHub Actions workflows (.github/workflows/) locally, everything except publishing. Run every task from the repository root.

3.1. Prerequisites

  • JDK 21 or later

  • Clojure CLI tools

  • babashka (bb)

  • Node.js 24 or later, for the four bundled SPAs. If you use nvm, activate it first (e.g. nvm use 24). The build fails fast with a hint if the active Node is too old.

  • Python 3.11 or later, only if you want to build the Python client or run bb test. The tasks use the interpreter PLAID_PYTHON names, else PLAID_AGENT_PYTHON, else the python of a plaid-agent environment in a mamba or conda install in your home directory (such as ~/miniforge3), never the first python on PATH. Otherwise skip the client build with --skip-clients.

3.2. Build

bb build

This builds the SPAs, bundles them, the JavaScript client and the official services into plaid-core/resources/, compiles the uberjar, boot-smoke-tests it on port 8080 (its /health, each app and the client), and packs the npm tarball plus the Python sdist and wheel. Artifacts land in dist-artifacts/:

java -jar dist-artifacts/plaid-0.0.0-alpha.0.jar

The version defaults to 0.0.0-alpha.0 and may be given as an argument (bb build 0.2.0-alpha.1). In CI the git tag is the sole source of truth for the version. Locally it is just an argument.

Useful flags:

  • --skip-clients: build only the jar (skips npm and Python packaging, and their toolchain requirements).

  • --no-smoke: skip the jar boot test. Needed if something else already answers on port 8080, unless you set PLAID_SMOKE_PORT to a free port instead.

Note
bb build leaves the built SPAs, services, and version.edn inside plaid-core/resources/ (all gitignored). Run bb clean to remove them before starting a plain development server, or the dev server will serve the stale bundled SPAs.

3.3. Other Tasks

bb test

Run every test suite: plaid-core, each JavaScript package and the Python packages, as the nightly workflow runs them.

bb ci

bb test followed by bb build.

bb docs

Build this documentation site into _site/ for local preview. Requires gem install asciidoctor coderay.

bb clean

Remove all local build outputs.

bb release-gate [rev]

Check that a commit (default HEAD) passed CI and a nightly run. Requires gh, signed in.

bb release <version>

Tag and push a release, and CI does the rest. Requires a clean tree on master and bb release-gate passing on HEAD.

Run bb tasks for the full list.

3.4. Releases

A release is cut from a commit on master that has already passed two GitHub Actions workflows: CI (ci.yml, run on every push) and a nightly run (nightly.yml, every unit suite plus the fidelity round trips and the Playwright suites). The release workflow does not run the suites again. Its first job checks both runs through the GitHub API and stops before building when either is missing, still running or red. A nightly run whose suites were skipped, on a night master did not move, does not count.

  1. Push master: git push origin master.

  2. Wait for CI on that commit.

  3. Start a nightly run on it, unless a night already tested it: gh workflow run nightly.yml --ref master. Wait for it.

  4. Run bb release <version>, for example bb release 0.2.0-alpha.1. It checks the same two runs on HEAD and refuses to tag without them, then tags HEAD and pushes the tag.

The tag starts release.yml, which builds the jar, the npm package and the Python package, smoke-tests the jar and publishes all three. When the release stops at its first job, because CI or the nightly run had not passed, nothing has been built: get the missing run to pass and re-run the same release run (gh run rerun <run id>), at the same version number. A version number whose build or publish failed is not used again: the next attempt takes the next number.

4. Working on plaid-core

  • clojure -X:dev: start the development server, and an nREPL server on port 7888. See localhost:8085

  • clojure -M:test: run the tests

  • clojure -M:test --jobs auto: run them on several JVMs at once (half the cores, at most 8), balanced by src/test-runner/test-timings.edn. --jobs N picks the count, --shard I/N runs one shard of that split, --record-timings rewrites the timings file, and --slowest K lists the slowest tests.

  • clojure -M:outdated: find outdated dependencies

  • clojure -X:uberjar: compile the jar alone (without the SPA bundling bb build does)

  • clojure -M:nrepl: start an nREPL server

  • clojure -M:format fix: apply cljfmt, the project’s formatter

Note
The client libraries are maintained separately in plaid-client-js/ and plaid-client-py/, each with its own tests.

4.1. OpenAPI Support

(On a release jar, substitute port 8080.)

5. Working on the SPAs

Each SPA is an ordinary Vite project. From plaid-ud/ or plaid-igt/:

npm install
npm run dev

The dev servers proxy API requests to the development server on port 8085. See each project’s vite.config.js. JavaScript, JSX, and CSS in the apps and plaid-ui are formatted by Prettier, and plaid-core’s Clojure by cljfmt, both applied to staged files by the tracked hook in .githooks/ (enable once per clone with git config core.hooksPath .githooks).

The tests and scripts that read real sample files (FieldWorks backups, .flextext exports) look for them in ~/.plaid_fixtures, or in the folder the PLAID_FIXTURES environment variable names, and skip with a note when a file is missing.

6. Database Access

Plaid stores everything in a single SQLite database at data/plaid.db (configurable via [database] path). You can inspect it with any SQLite client:

sqlite3 data/plaid.db

The database runs in WAL mode, so a plain file copy misses un-checkpointed writes in the -wal sidecar. For an ad-hoc backup of a running server, use the SQLite backup API:

sqlite3 data/plaid.db ".backup /path/to/backup-$(date +%F).db"

The server also takes automatic nightly snapshots. See the [backup] section of data/config.toml.