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
- Architecture · Testing, docs and release · Server with Docker