Skip to content
DashboardWebsite

Storage Layer

The storage layer defines persistence interfaces for the platform and product domains. PlatformStorageBackend covers identity, orgs, admin, and observability. ProductStorageBackend covers resources, findings, jobs, and analysis configuration. StorageBackend combines both interfaces, and MongoBackend implements it. MongoDB is the only storage backend. One connection and one database serve both halves. To store only platform data, implement PlatformStorageBackend without the product interface.

classDiagram
    class StorageLifecycle {
        <<abstract>>
        +setup()
        +close()
        +ping()
    }
    class PlatformStorageBackend {
        <<abstract>>
        +organizations, users, identities, memberships
        +api keys, invites, teams, org roles, user tokens
        +SSO connections, SCIM configs
        +notification channels, Slack apps, OAuth states
        +usage events, trial usage, spans, audit events
        +jobs: create / claim_job / renew_job_lease / requeue_expired_jobs / sweep_stuck_jobs
        +platform settings, pricing, retention and job sweep state
        +rate limits: hit / peek / clear
        +delete_X_for_org(org_id) "platform half of an org purge"
    }
    class ProductStorageBackend {
        <<abstract>>
        +store_units() / read_resource() / set_analysis()
        +start_revision() / current_revision() / list_revisions() / list_changesets()
        +claim_unanalysed() / release_claims() "a unit goes to one caller at a time"
        +set_changeset_review() / review_teams_for_changesets()
        +upsert_finding() / update_finding_status() / set_finding_teams()
        +custom rules, rule categories, report templates, installed packs
        +LLM connections, allowed models
        +integrations, PR gates, manifest states, report links
        +repositories, repository ownership, products
        +review feedback, rule proposals
        +purge_findings() / redact_stale_resources() "retention"
        +delete_X_for_org(org_id) "product half of an org purge"
    }
    class StorageBackend {
        <<abstract>>
        +both halves "what core's routes and services take"
    }
    class PlatformMongoBackend {
        +platform collections and indexes
    }
    class _ProductMongoMixin {
        -resources "_id = org_id:hash"
        -changeset_entries "_id = org_id:changeset:revision_id:hash"
        -changesets "_id = org_id:changeset"
        -llm_credentials "_id = org_id:connection_id"
        -findings "_id = org_id:hash:rule_id"
        -integrations "_id = org_id:provider"
        -repositories "_id = org_id:provider:external_id"
        -other collections: see the config reference
    }
    class MongoBackend
    StorageLifecycle <|-- PlatformStorageBackend
    StorageLifecycle <|-- ProductStorageBackend
    PlatformStorageBackend <|-- StorageBackend
    ProductStorageBackend <|-- StorageBackend
    PlatformStorageBackend <|-- PlatformMongoBackend : implements
    ProductStorageBackend <|-- _ProductMongoMixin : implements
    PlatformMongoBackend <|-- MongoBackend
    _ProductMongoMixin <|-- MongoBackend
    StorageBackend <|-- MongoBackend

usage_events and audit_events are deliberately excluded from the org-offboarding cascade. They remain associated with org_id instead of being deleted, so the audit trail survives the event it describes.

Route handlers access storage through FastAPI’s Depends. No router imports MongoBackend directly.