GraphQL & gRPC surface — Parelion Docs

/ 01GraphQL schema

The GraphQL endpoint is the primary client surface. Schema is delivered via SDL; clients should pin to a published schema version and update on schema deprecations.

type Query {
  search(query: String!, filters: SearchFilters): SearchResult!
  claim(id: ID!, asOf: DateTime): Claim
  entity(id: ID!): Entity
  document(id: ID!): Document
  accessRequests(status: AccessStatus): [AccessRequest!]!
  stewardQueue(silo: ID!, filter: QueueFilter): [QueueItem!]!
}

type SearchResult {
  items: [SearchHit!]!
  total: Int!
  facets: FacetSet!
}

type SearchHit {
  claim: Claim
  document: Document
  disclosureLevel: DisclosureLevel!   # L0..L6 per requester
  score: Float!
  requestAccessUrl: String            # null if requester at max
}

/ 02Key queries

Cross-silo search

query Search($q: String!) {
  search(query: $q, filters: { jurisdiction: "eng", year: { from: 2024 } }) {
    total
    facets { jurisdiction { value count } practiceGroup { value count } }
    items {
      disclosureLevel
      requestAccessUrl
      claim {
        id
        predicate
        objectValue
        sourceDocument { owningSiloId }
      }
    }
  }
}

Entity drill-down

query Entity($id: ID!) {
  entity(id: $id) {
    id
    canonicalName
    neighbours(depth: 2) {
      relationship
      entity { id canonicalName }
    }
    claims { id predicate objectValue }
  }
}

/ 03Mutations

Sensitive mutations require step-up. See step-up authentication.

type Mutation {
  requestAccess(resourceId: ID!, targetLevel: DisclosureLevel!, reason: String!): AccessRequest!
  approveAccess(requestId: ID!): AccessGrant!     # step-up required
  reclassify(documentId: ID!, to: Classification!, reason: String!): Document!   # step-up required
  reviewQueueItem(itemId: ID!, outcome: ReviewOutcome!, edits: JSON): QueueItem!
}

/ 04gRPC services

Internal service-to-service uses gRPC over mTLS. Five services:

Service	Purpose
`atrium.connectors.v1`	Connector orchestration · ingest event bus
`atrium.inference.v1`	Embedding · extraction · disclosure-asset generation
`atrium.policy.v1`	OPA decision service
`atrium.audit.v1`	Audit log writer · anchorer · WASM verifier blob
`atrium.disclosure.v1`	Asset generation · steward queue

Proto files live in proto/atrium/ and are versioned independently of the server.

/ 05Authentication

Both surfaces accept the same identities, expressed differently:

GraphQL — Bearer JWT in Authorization header; JWKS-verified against the configured IdP
gRPC — mTLS with SPIFFE-style identities; client certificates issued by Atrium's internal PKI (Phase 3+: SPIFFE/SPIRE)

Sessions carry the principal's silo memberships, clearances, ethical-wall recusals, matter assignments, role, and current ACR. The RequesterContext (see Rego policies) is built from these and passed to every policy decision.

/ 06Rate limits

Tier	Search QPS	Mutations / minute
Sovereign · S	2 sustained · 20 burst	30
Federated · F	20 sustained · 200 burst	120
Connected · C	200 sustained · 2,000 burst	600

Limits apply per tenant. Per-user sub-limits configurable; default 30% of tenant ceiling for any single user.

/ 07Region pinning

Every silo is pinned to a region (Frankfurt, London, Zürich, Paris). Queries are routed to the silo's region for any data physically pinned there — extracted text, silo-specific claims, silo-pinned disclosure assets.

Tenant-scope data — canonical entity master register, group-level policies — lives in the tenant's primary region. Cross-region replication is synchronous for audit log durability within the same legal jurisdiction; no cross-jurisdiction replication.

GraphQL & gRPC.