Skip to content
DashboardWebsite

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.

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.

from opentremor_platform.controllers.app import create_platform_app
app = create_platform_app() # a complete, runnable multi-tenant API

Run it directly:

Terminal window
CONFIG_FILE=configs/opentremor-platform-local.yaml \
uvicorn opentremor_platform.controllers.app:app --reload

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=...).

create_platform_app() returns a FastAPI application. A product can add its own routers and register its services with the platform:

What the product contributesRegistration point
Admin-editable config sectionscontrollers/services/settings_registry.py — REGISTRY.register
Retention and cleanup sweep stepscontrollers/services/sweep_registry.py — register_sweep_step
Rows to delete when an organization is purgedcontrollers/services/org_purge_registry.py — register_org_purge_step
Collections to include when an organization exports its datacontrollers/services/org_export_registry.py — register_org_export_section
MongoDB index declarationscontrollers/storage/index_registry.py — register_index_declarations
Seeding when an organization is createdcontrollers/shared/org_bootstrap.py — register_org_bootstrap_hook
One-time startup seedingcontrollers/shared/startup.py — register_startup_hook
Config class that names collections for prepare-mongodbcontrollers/storage/mongo_admin.py — configure_storage_classes
Product installation capabilitycontrollers/services/capability_registry.py — register_capability
Notification event typescontrollers/services/notification_events.py — register_notification_event
Usage meters for counting, billing and trialscontrollers/services/billing/meters.py — register_meter
Permissions required by org-scoped endpointscontrollers/services/auth/permissions.py — register_permission
Email templatescontrollers/services/mail/templates.py — register_mail_template
Job kinds that any replica can processcontrollers/services/jobs/kinds.py — register_job_kind
Published address ranges an admin can allowcontrollers/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.

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.

An org-scoped endpoint checks a permission, not a role:

from opentremor_platform.controllers.dependencies import require_permission
from opentremor_platform.controllers.services.auth.permissions import register_permission
from 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:

  • auditor holds permissions marked read_only=True and no others. Mark product read permissions as read-only for auditors to hold them. See OpenTremor-platform#0019.
  • pipeline holds permissions marked pipeline=True and no others. Use it for API keys that need product permissions for automated workflows. See OpenTremor-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.

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 type of its usage events, recorded with storage.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 with entitlements.org_is_entitled(org, mode, meter) before doing the work. Count a use with entitlements.consume_trial(storage, org, mode, meter), which increments the counter atomically.
  • Before paid work, check services/billing/budget.remaining_budget_usd. It raises BudgetExceeded when the org reaches its monthly spend cap.

A self-hosted deployment is always entitled, regardless of its plan.

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.

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_kind
from 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.

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.

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.

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.