Skip to content
DashboardWebsite

Architecture

OpenTremor has two Python packages at its center: opentremor-platform, which provides the multi-tenant base, and opentremor-core, which adds security analysis. Packs are separate plugin packages.

This page explains the request lifecycle, resource hashing, and request correlation. Other architecture topics have their own pages:

PageWhat’s in it
Module mapModules in the platform and core packages
Platform / product compositionThe app factories, registration points, and seams
Platform baseWhat opentremor-platform provides
Data modelCollections, relationships, and multi-tenant scoping
Storage layerStorage interfaces, the MongoDB backend, and index management
Analysis enginePack plugins, auto-routing, server-side analysis, and findings lifecycle
Billing & quotaDeployment-mode entitlement and per-org spend caps
GitHub App integrationEach organization’s App, manifest flow, and PR round-trip
flowchart TD
    A[HTTP Request] --> B[CORSMiddleware]
    B --> C[CorrelationIdMiddleware\nassigns or forwards X-Request-ID]
    C --> D[NetworkAccessMiddleware]
    D --> E[RequestSpanMiddleware\nlogs the request and records a span when telemetry is enabled]
    E --> F[Prometheus instrumentation\ntimes the request by route template]
    F --> G[FastAPI Router\npath matching and dependency injection]
    G --> H["Route dependencies\nmay resolve require_permission(name)\n-> AuthContext"]
    H --> I["Route dependencies\nmay resolve get_storage()\n-> app.state.storage"]
    H --> J["Route dependencies\nmay resolve get_registry()\n-> app.state.registry"]
    I --> K[Route Handler]
    J --> K
    K --> L1["storage calls"]
    K --> L2["registry.get(name)\n-> pack methods such as ingest() or get_rules()"]
    L1 --> M[Response]
    L2 --> M

Routes use dependencies according to their needs. A route protected by require_permission resolves an AuthContext; routes that access storage or the pack registry resolve those dependencies as well. When authentication is disabled, the platform resolves callers as the anonymous owner of the default org. Storage calls that operate on org data use an org ID; some platform-wide data is not org-scoped.

Core hashes a resource’s content with SHA-256 after normalizing it. It removes blank lines, trims surrounding whitespace from each line, and drops any line containing a Terraform plan-time placeholder:

  • (known after apply)
  • (sensitive value)
  • (will be computed)

These values can change based on when Terraform rendered the plan, rather than on the resource itself. Resources with the same remaining content therefore get the same hash.

The platform assigns an X-Request-ID to each request and returns it in the response. It keeps a caller-supplied ID if it is a UUID or 32-character hexadecimal value. Otherwise, it replaces the value with a fresh ID.

Request spans use this ID as their trace_id. Audit events use it as their request_id. Search /metrics/spans or the audit log for the ID to follow a request.