Developer guide
Architecture
Two ways to run
- One site (
readiness serve, or the Docker services per site): the app for one site, with its own settings, database and files. The desktop shortcut and a site server run this way. - Many companies (
readiness host,ORT_TENANCY=1): one service for every company and site on the platform, with a directory of companies, sites, people, platform administrators and plugin publishers, company-scoped sign-in, the platform console and the publisher portal. Each site still has its own runtime (settings, database, files), opened on demand.
The packages
| Path | What |
|---|---|
src/readiness/settings.py |
Where things are: the ORT_* environment variables (ORT_HOME, ORT_SITE, ORT_DATABASE_URL, ORT_STORAGE, ORT_CONFIG_DIR, ORT_DATA_DIR ...) |
runtime.py |
Runtime: everything a service needs, opened once: settings, the site, the database, the modules |
db.py, migrate.py |
The database (SQLite or Postgres, by URL) and its portable schema upgrades |
storage.py |
Files: a local folder or an S3-compatible bucket |
settingsdb.py, config_edit.py |
Settings kept in the database with their history; YAML for import and export |
jobs.py, worker.py, tasks.py, scheduler.py |
The job queue and its worker; scheduled tasks and their scheduler |
modules/ |
The tools: platform, drawings, context (the documents), assets, plugins, and their API routers |
ims.py, ims.yaml, standards.py |
The management system: clauses, requirements of each standard, the tools that meet them |
analysis.py, toolkinds.py, toolkinds.yaml, prompts/ |
The documents: their schemas, how Claude writes and reviews them |
layouts.py, reports.py, sharepoint.py |
Word, Excel, Markdown and SharePoint output |
assetinfo.py, registers.py, tos.py, reliability.py, assetclaude.py |
Asset information: the registers, the structure, failure statistics, Claude's proposals |
plugins/ |
The plugin engine, the wasm sandbox, native (built-in) plugins, review and publishing, builtin/ manifests |
tenancy.py, identity.py, accounts.py |
The multi-company directory, sign-in (Argon2id, authenticators, recovery codes), single-site accounts |
claude.py |
The Claude connection: provider, sealed credentials, checks, usage |
web/app.py, web/host.py, web/auth.py |
The API, sign-in and the built front end |
src/drawreg/ |
The drawing register (The drawing register) |
frontend/ |
The React and TypeScript source (Vite); npm run build writes src/readiness/web/static/ui (committed) |
docs/guide/ |
The user guide: in-app help and the wiki |
A request
The front end loads /api/app once (the site, the menu from ims.navigation, the documents of clauses 6 to 10 from
toolkinds.meta(), the installed plugins) and builds its routes from it.
A job
Nothing slow runs in a request. A route queues a job (jobs.enqueue(db, type, payload, label=..., by=...)) and
returns its number; the Tasks page shows it.
The drawing register's steps run as a subprocess inside a job (python -m drawreg.cli <step> --config ...), so a crash in a
converter cannot take the worker down, and Stop ends the whole process tree. A job left running when a worker dies is
queued again when it starts.
Scheduled tasks
A TaskDef names a function and when it runs (every_seconds, or daily_at in the site's time zone). Whether each is
on, and how its last run went, is kept in the database and shown on Tasks. Plugins' schedules run the same way.
Settings
Each site's settings are files of a module (SettingsFile: a pydantic model, a seed for a new site, its secrets), kept in
the database with every change's history, editable as a form or as YAML on Settings. What every site shares
(the company, the standards) is kept once. Secrets are encrypted at rest and never shown again.
Where data lives
| What | Where |
|---|---|
| Documents, their versions, comments, reviews | The site's database |
| Shared documents (corporate plan, SAMP) | The corporate database, shared by every site of the company |
| Registers (asset information), plugin records | The site's database |
| Drawings' copies, PDFs, thumbnails, the register's files | The site's output folder (or the person's own folder, on hosted IMS Creator) |
| Uploads (reports, templates, exports) | The site's uploads (local or S3) |
| Companies, sites, people, sign-ins, audit log | The directory (multi-company) |
See also
- Setting up · Documents · Plugins
docs/ARCHITECTURE.mdanddocs/CLOUD-ARCHITECTURE.mdin the repository, for the design in full