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.
Many companies:readiness host

Web: sign-in, directory, console, publisher portal

Runtimes: one per company site, opened on demand

Worker and scheduler over every site

Directory database

One site: readiness serve

Web (FastAPI)

Worker

Scheduler

site database + files

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

DatabaseModule routerFastAPI appBrowserDatabaseModule routerFastAPI appBrowserGET /api/... (session cookie, and the CSRF header on writes)Who is it, and may they? (role: viewer, engineer, site admin)The module's routeRead or writeJSON

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.

Job handlerWorkerJob queue (database)RouteJob handlerWorkerJob queue (database)Routeenqueue(type, payload)take the most urgent, then the oldestrun it with a JobContext (progress, log, stop?)one sentence for the person reading Tasksdone / failed (with the error)

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.md and docs/CLOUD-ARCHITECTURE.md in the repository, for the design in full