Skip to content
Toprent.app Docs

10. Lightweight GraphQL Context for External API Proxies

Date: 2025-12-16

Status

Accepted

Context

GraphQL queries that proxy external APIs (e.g., Google Places) were experiencing performance degradation. Full context initialization includes feature flags fetching, database verification, tenant resolution, settings loading, and plan loading—operations unnecessary for simple passthrough calls to external services.

Response times for these queries were significantly slower than needed because they executed the entire context creation pipeline despite not using most context fields.

Decision

Implement a two-tier context system in the GraphQL layer:

  1. Full context (default): All queries and mutations use the standard createResolversContext with full authentication and tenant resolution.

  2. Lightweight context (opt-in): Allowlisted queries that meet strict criteria use minimal context containing only isLightweight: true.

Criteria for lightweight context:

  • Request must be a query (mutations always excluded)
  • Request must include a Relay operation identifier (body.id) which is already covered by React-relay
  • Operation identifier must be explicitly allowlisted in LIGHTWEIGHT_QUERIES
  • Request must still be authenticated at transport level

Design choice: Check only operation identifier, not query content, to avoid false positives when larger queries include fragments referencing lightweight resolvers.

Consequences

Benefits

  • Performance: External API proxy queries respond faster without unnecessary initialization
  • Explicit opt-in: Allowlist prevents accidental bypass of security checks
  • Transport auth maintained: Lightweight queries still require valid authentication tokens

Risks & Mitigations

  • Misclassification: Query added to allowlist but actually needs full context
    • Mitigation: Documentation and code comments clearly define when queries qualify; resolvers can check ctx.isLightweight flag
  • Maintenance burden: Developers must understand two context paths
    • Mitigation: Clear documentation in 04-graphql-api.md with step-by-step guide for adding lightweight queries
  • Security: Bypassing tenant resolution could expose data if query needs it
    • Mitigation: Only operation IDs can be allowlisted; transport-level auth still enforced; the light context doesn’t provide data layer access

Implementation

  • server/graphql/helpers/lightweightContext.ts: Detection logic and minimal context creation
  • lib/graphql/yogaHandler.ts: Routes to lightweight context when criteria met
  • .cursor/rules/project-description/04-graphql-api.md: Developer documentation