OpenTremor Platform architecture
opentremor-platform provides OpenTremor’s multi-tenant services: users, organizations, memberships, authentication, teams, invitations, service-account API keys, platform administration, billing, telemetry and audit logging. It does not define what a mounted product does.
opentremor-core is one consumer. It mounts the security-analysis engine on the platform.
Why the platform is separate
Section titled “Why the platform is separate”Core combines multi-tenant services with infrastructure-as-code security analysis. The platform contains the reusable multi-tenant services; the analysis engine is specific to OpenTremor. A project can use the platform without taking on the analysis engine.
The split is reflected in the test setup: the platform test suite runs without opentremor-core installed.
Run the platform on its own
Section titled “Run the platform on its own”from opentremor_platform.controllers.app import create_platform_app
app = create_platform_app() # a complete, runnable multi-tenant APIRun it directly:
CONFIG_FILE=configs/opentremor-platform-local.yaml \ uvicorn opentremor_platform.controllers.app:app --reloadConfigure the platform
Section titled “Configure the platform”The repository includes two example configs: configs/opentremor-platform-local.yaml uses MongoDB on
localhost:27017 for development; configs/opentremor-platform.yaml is for deployment and names
each platform collection.
The platform reads only storage, cors, auth, jwt, two_factor, secrets and deployment
from the config file. Other settings are managed at runtime through GET and PATCH /v1/admin/settings. File values for those settings are discarded, and the platform uses hardcoded
defaults at boot. See Configuration reference
for the rationale. The same behavior applies to a platform-only deployment.
The platform config model is PlatformConfig. A host that mounts a product widens this model
(see Sections that span both halves) and passes its config to
create_platform_app(config=...).
Mounting a product on top
Section titled “Mounting a product on top”create_platform_app() returns a FastAPI application. A product can add its own routers and
register its services with the platform:
| What the product contributes | Registration point |
|---|---|
| Admin-editable config sections | controllers/services/settings_registry.py — REGISTRY.register |
| Retention and cleanup sweep steps | controllers/services/sweep_registry.py — register_sweep_step |
| Rows to delete when an organization is purged | controllers/services/org_purge_registry.py — register_org_purge_step |
| Collections to include when an organization exports its data | controllers/services/org_export_registry.py — register_org_export_section |
| MongoDB index declarations | controllers/storage/index_registry.py — register_index_declarations |
| Seeding when an organization is created | controllers/shared/org_bootstrap.py — register_org_bootstrap_hook |
| One-time startup seeding | controllers/shared/startup.py — register_startup_hook |
Config class that names collections for prepare-mongodb | controllers/storage/mongo_admin.py — configure_storage_classes |
| Product installation capability | controllers/services/capability_registry.py — register_capability |
| Notification event types | controllers/services/notification_events.py — register_notification_event |
| Usage meters for counting, billing and trials | controllers/services/billing/meters.py — register_meter |
| Permissions required by org-scoped endpoints | controllers/services/auth/permissions.py — register_permission |
| Email templates | controllers/services/mail/templates.py — register_mail_template |
| Job kinds that any replica can process | controllers/services/jobs/kinds.py — register_job_kind |
| Published address ranges an admin can allow | controllers/services/network/presets.py — register_address_list_preset |
This follows the pack plugin system: the platform defines registration interfaces, and installed products register with them.
Sections that span both halves
Section titled “Sections that span both halves”Three config sections span the platform and product: storage.mongodb for collection names, server for public URLs and ingest limits, and retention for telemetry, audit and product purge windows. The platform declares each section with a narrower type. The host widens the type, so the combined deployment keeps one config with the same attribute paths.
The platform keeps retention as one section. This allows the combined deployment to use one sweep, state document, endpoint and task-scheduler entry.
Use permissions for org-scoped endpoints
Section titled “Use permissions for org-scoped endpoints”An org-scoped endpoint checks a permission, not a role:
from opentremor_platform.controllers.dependencies import require_permissionfrom opentremor_platform.controllers.services.auth.permissions import register_permissionfrom opentremor_platform.models.auth import OrgRole
EXPORTS_RUN = register_permission( "exports:run", description="Start an export.", default_role=OrgRole.member,)
@router.post("/exports")async def start_export(auth: AuthContext = Depends(require_permission(EXPORTS_RUN))): ...Memberships, API keys, invitations and SCIM group mappings store roles. A role grants permissions according to its place on the built-in ladder: viewer < member < admin < owner. The dependency also enforces checks shared by org-scoped endpoints: a locked org returns 423; a suspended membership or missing required 2FA returns 403. GET /v1/auth/me returns the caller’s permissions, and GET /v1/permissions lists declared permissions. Clients can check a permission before offering an action. See OpenTremor-platform#0011.
Two built-in roles sit outside the ladder:
auditorholds permissions markedread_only=Trueand no others. Mark product read permissions as read-only for auditors to hold them. SeeOpenTremor-platform#0019.pipelineholds permissions markedpipeline=Trueand no others. Use it for API keys that need product permissions for automated workflows. SeeOpenTremor-platform#0029.
An org can define custom roles at /v1/orgs/{org_id}/roles. Each custom role is a named set of permissions stored as custom:<slug>. It holds only the permissions listed on it. If a product declares a permission later, custom roles do not gain it until someone adds it.
An API key can have scopes that narrow its role’s permissions; scopes cannot add permissions. The platform resolves permissions on every request, so custom role changes take effect immediately. A caller cannot assign a role or edit one to grant permissions they do not hold. Superadmins are exempt.
Register usage meters
Section titled “Register usage meters”The platform owns plans, trials, contracts, pricing and the monthly spend cap. Products register meters for the usage they count:
from opentremor_platform.controllers.services.billing.meters import register_meter
register_meter("seat", unit="seat", billed=True)register_meter("export", unit="export", trial_allowance=50)- A meter’s name is the
typeof its usage events, recorded withstorage.record_usage_event. The monthly quantity is the sum of those events. - At most one meter can be billed. Pricing tiers form one ladder, and an enterprise contract sets one monthly allowance for that meter with
included_units_per_month. - On a cloud deployment, a meter with a trial allowance is usable by a non-paying org until its lifetime counter (
Organization.trial_usage[meter]) reaches the allowance. Check entitlement withentitlements.org_is_entitled(org, mode, meter)before doing the work. Count a use withentitlements.consume_trial(storage, org, mode, meter), which increments the counter atomically. - Before paid work, check
services/billing/budget.remaining_budget_usd. It raisesBudgetExceededwhen the org reaches its monthly spend cap.
A self-hosted deployment is always entitled, regardless of its plan.
Encrypt stored secrets
Section titled “Encrypt stored secrets”secrets.encryption_key encrypts secrets at rest, including SSO client secrets, notification channel URLs and signing secrets, and secrets stored by a mounted product. Configure it in the file or through SECRETS_ENCRYPTION_KEY. It cannot be edited or returned by the API. Rotating the key makes stored secrets unreadable.
Background jobs
Section titled “Background jobs”A product can write a job document (JobRecord, which it may extend with product fields). The work function receives a progress callback and a liveness check:
async def work(progress_cb, should_continue) -> JobResult: for i, unit in enumerate(units, start=1): if not await should_continue(): return JobResult(fields={"done": i - 1}, stopped_early=True) ... await progress_cb(i, len(units), {"current_unit": unit.id}) return JobResult(fields={"done": len(units)})Queued jobs (the default). Register a job kind and enqueue a job with a payload of references. A worker on any replica can claim the job, load the remaining data from the payload and app state, and run the handler:
from opentremor_platform.controllers.services.jobs.kinds import register_job_kindfrom opentremor_platform.controllers.services.jobs.queue import enqueue_job
async def export_report(job, state, progress_cb, should_continue) -> JobResult: units = await load_units(state.storage, job["org_id"], job["payload"]["report_id"]) ...
register_job_kind("report.export", export_report)
await enqueue_job(storage, job_doc, kind="report.export", payload={"report_id": report_id})Each replica runs a worker configured by worker.enabled and worker.concurrency. A worker claims jobs atomically and holds each claim under a lease (worker.lease_seconds), which it renews while the job runs. If a replica dies, the lease expires and the job returns to the queue. After jobs.max_attempts claims, the job fails. A clean shutdown releases its jobs immediately. The payload is stored in the job document; include references, not secrets or input data.
In-process jobs. Work that closes over data held only by the accepting process, such as a credential passed with the request, runs in that process:
from opentremor_platform.controllers.services.jobs.runner import run_job, spawn
spawn(run_job(storage, org_id, job_id, work), name=f"export:{job_id}")Both paths share the job lifecycle. A job cancelled before it starts never runs. The platform records progress, and the job ends as done or failed with an error. If work stops early because should_continue() returns false, the platform keeps the status set by the cancelling process or stuck-job sweep. The sweep fails a running job that stops reporting progress, or an in-process job whose process died. It does not sweep a queued job waiting its turn. See OpenTremor-platform#0014.
Set deployment branding
Section titled “Set deployment branding”branding.product_name names the deployment in user-facing places, including the issuer shown for a TOTP entry in an authenticator app, the name of a Slack app an org creates, and the title of a test notification. It is admin-editable like registration. After create_platform_app() returns, a product sets its own OpenAPI title and description.
Store data in MongoDB
Section titled “Store data in MongoDB”MongoDB is the only storage backend. PlatformMongoBackend, which uses PyMongo’s async driver, implements PlatformStorageBackend. A platform-only deployment therefore has a working persistence backend. PlatformMongoBackend.setup() creates the platform’s indexes.
A host composing both halves builds its backend from PlatformMongoBackend and a product mixin. It also registers its wider config class with configure_storage_classes(), so POST /v1/admin/storage/prepare-mongodb prepares the full schema.
Licence
Section titled “Licence”The platform is licensed under GNU AGPL v3 or later, with the OpenTremor Pack Plugin Exception. See LICENSE and LICENSE-EXCEPTION in the repository root.