Developer guide

Setting up

What you need

For
Python 3.11 or later The app, the drawing register, the tests
Node 20 or later Only to change the front end (the built front end is committed)
Tesseract OCR Searchable PDFs and reading scanned title blocks (apt-get install tesseract-ocr; on Windows setup.ps1 installs it)
ODA File Converter Only for DWG files (its licence must be accepted by hand; DXF files need nothing)
Rust with the wasm32-unknown-unknown target Only to build plugin functions
A Claude connection Only for the parts Claude writes; everything else, and the whole test suite, runs without one

The first time

git clone <the repository> IMS Creator && cd IMS Creator
python -m venv .venv && . .venv/bin/activate        # Windows: .\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"                              # the app, drawreg, and pytest, httpx, moto
python -m pytest -q                                  # the whole suite: a few minutes, no network, no Claude

Running the app

python -m readiness.cli bootstrap                    # folders, settings, database and the first admin
python -m readiness.cli serve                        # web, worker and scheduler: http://127.0.0.1:8765

serve runs the worker and scheduler as threads of the same process; on a server they run as their own services (readiness worker, readiness scheduler). readiness host runs the multi-company host instead (ORT_TENANCY=1). ORT_HOME chooses the folder the sites live in, ORT_SITE the site.

To see every page with sensible content and no company's data, build the demo site (made-up company, site, documents, drawings and plugin records):

python scripts/docs/demo_site.py /tmp/demo --serve --port 8796

Changing the front end

cd frontend
npm install
npm run dev          # the pages from source, with /api proxied to the app on 8765
npx tsc --noEmit     # typecheck
npm run build        # writes src/readiness/web/static/ui: commit it with the change

The pages are in frontend/src/views/, the shared pieces in frontend/src/components/ (PageHead, Card, DataTable, useLoad, useAction, Help). A page names its help page with help="<Page>"; a test checks every such page exists in docs/guide.

Claude

Add a connection on Settings, Claude (a site) or Company, Claude connection (every site of a company): Anthropic's API, Amazon Bedrock or Google Vertex AI. For the drawing register's command line, ANTHROPIC_API_KEY in the environment does. Keys are kept sealed, never in the repository: .env files and the sites' folders are ignored by Git.

The command lines

Command What
readiness serve / host / worker / scheduler / bootstrap Run the app and its services
readiness company-add, site-add, person-add, domain-add, breakglass The directory, from the server
readiness plugin-check <folder or bundle>, plugin-pack <folder> -o <bundle> Check and pack a plugin
readiness jobs, tasks, companies What is running
readiness export-settings / import-settings, copy-to-postgres, copy-to-s3 Settings and moving data
drawreg run The drawing register's whole pipeline; or one step: scan, copy, convert, ocr, split, extract, claude, summarise, transcribe, pdf2dwg, register, eam, report
drawreg status, survey, rerun, correct, ui The register's state, a survey of a folder, re-running files, corrections, the app

Every command has --help.

See also