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:
|
The Clojure server: REST API, data model, storage, audit log, query engine. Also holds this documentation under |
|
The bundled Universal Dependencies editor (a Vite/React SPA), served from the jar at |
|
The bundled interlinear glossed text editor (a Vite SPA), served from the jar at |
|
The bundled dictionary reader (a Vite/React SPA), served from the jar at |
|
The bundled Uniform Meaning Representation editor (a Vite/React SPA), served from the jar at |
|
The component and helper package the four SPAs share. Not published: each app resolves it from the checkout. |
|
The Python assistants for UD, IGT and UMR, one distribution named |
|
The official JavaScript client, published to npm as |
|
The official Python client, published to PyPI as |
|
Small standalone demos built against the clients. |
|
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
-
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 interpreterPLAID_PYTHONnames, elsePLAID_AGENT_PYTHON, else the python of aplaid-agentenvironment in a mamba or conda install in your home directory (such as~/miniforge3), never the firstpythononPATH. 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 setPLAID_SMOKE_PORTto 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
|
Run every test suite: |
|
|
|
Build this documentation site into |
|
Remove all local build outputs. |
|
Check that a commit (default |
|
Tag and push a release, and CI does the rest. Requires a clean tree on |
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.
-
Push
master:git push origin master. -
Wait for CI on that commit.
-
Start a nightly run on it, unless a night already tested it:
gh workflow run nightly.yml --ref master. Wait for it. -
Run
bb release <version>, for examplebb release 0.2.0-alpha.1. It checks the same two runs onHEADand refuses to tag without them, then tagsHEADand 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 bysrc/test-runner/test-timings.edn.--jobs Npicks the count,--shard I/Nruns one shard of that split,--record-timingsrewrites the timings file, and--slowest Klists the slowest tests. -
clojure -M:outdated: find outdated dependencies -
clojure -X:uberjar: compile the jar alone (without the SPA bundlingbb builddoes) -
clojure -M:nrepl: start an nREPL server -
clojure -M:format fix: applycljfmt, 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
-
Playground: localhost:8085/api/v1/docs/index.html#/
(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.