Viaduct GraphQL Data-Oriented Service Mesh

Viaduct is designed with two distinct user roles. If you are building application logic (resolvers, schemas, etc.), refer to the Developers documentation.

If you are a Service Engineer, your role involves managing the Viaduct service infrastructure. This includes:

• Integrating Viaduct into your organization's web-serving stack (HTTP frameworks, message consumers).
• Configuring tenant module composition for multi-tenancy.
• Extending the schema with shared types and directives.
• Integrating with dependency-injection (DI) frameworks.
• Setting up observability, monitoring, and alerting.

The Micronaut Viaduct Starter is a minimal template for building Viaduct GraphQL applications using the Micronaut framework. It provides a bridge between Viaduct and Micronaut's dependency injection (DI) system, allowing you to use Micronaut annotations like @Singleton and @Factory within your Viaduct resolvers.

Key capabilities include:

• Full DI Support: Resolvers can have dependencies injected via Micronaut's DI container.
• Production Ready: The application runs as a full Micronaut HTTP server.

Key updates in this release include:

• Exception Hierarchy: ViaductException now implements TenantException.
• Validation: Strict missing-resolver validation is performed at startup. DefaultSchemaValidator and ViaductServiceValidation (at CI-time) include two new OSS schema validation rules.
• Bootstrapping: Added file-driven bootstrapping for demoapps and changes to the file-based bootstrapping API surface.
• Annotations:
  • Node resolvers now require the @Resolver annotation.
  • providedVariables can now be populated from the @Variables nested class annotation.
• KSP Support: Added KSP-based module config file generation and additional KSP fields to support schema-less bootstrapping.

The Star Wars demo application illustrates how Viaduct's core building blocks compose into a single runnable server. The architecture is organized around tenants (e.g., universe and filmography). Each tenant owns a specific portion of the schema and its corresponding resolver code. These tenants compose together to form the complete system.

Key concepts covered in this section include:

• Schemas: The structural definition of the data.
• Resolvers: The logic that fetches data for specific fields.
• Scopes: The boundaries within which resolvers operate.
• Global IDs: Unique identifiers used across the system.
• Batching: Mechanisms to optimize data fetching and prevent N+1 problems.

The Star Wars demo application demonstrates how to use Viaduct as a GraphQL runtime within a Kotlin and Spring Boot environment. The architecture is built around a multi-tenancy model where different logical modules (scopes) maintain isolated schemas and resolvers.

Key architectural features include:

• Runtime: Kotlin on Spring Boot using Viaduct.
• Tenancy Model: Multiple logical modules (scopes) with isolated schemas and resolvers.
• Data Layer: Uses in-memory data sets (e.g., StarWarsData) which are designed to be replaceable with persistent stores (SQL/NoSQL) without altering the public schema.
• Performance & Stability: Implements batching, caching, and type-safe Global IDs to mitigate N+1 problems and ensure stable object references.

The ViaductSchema binary format is a compact, efficient representation of GraphQL schemas designed for build-time tooling and runtime loading. It prioritizes fast, single-pass decoding with minimal heap allocations through deduplication and index-based references.

Key Characteristics:

• Compactness: Uses lookup tables (identifiers, source locations, etc.) and references them via 20-bit indices.
• Self-Contained: Includes all necessary schema information for runtime.
• Not for Archival: This is a working format; use GraphQL SDL for long-term storage.
• Section-Based: The file is organized into sequential, 4-byte aligned sections (e.g., Header, Identifiers, Definitions).

Viaduct is designed to scale from small GraphQL servers to massive supergraphs. It emphasizes developer ergonomics and is suitable for both new projects and large-scale production environments.

Key characteristics include:

• Scalability: Proven to handle massive graphs and hundreds of tenants.
• Modern Engine: A production-ready engine that supports evolving API patterns.
• Batch Resolvers: A feature in the Modern API designed to smooth the adoption of the data-loader pattern, improving performance by batching requests.

The viaduct.tenant.api package is the primary interface for tenants integrating with the Viaduct Framework. Tenants use this API to define how their GraphQL schema behaves. Specifically, it provides the mechanisms to implement:

• Field and Node @resolvers: Logic for resolving specific GraphQL fields or nodes.
• Custom Access Checkers: Logic for enforcing security and access control rules on the schema.

Custom directives in Viaduct are schema annotations used to enhance GraphQL schemas with extra behavior and validation. Viaduct interprets these directives during the planning or execution phase, allowing you to express resolver hints, identity types, and visibility rules directly in your schema without requiring additional Kotlin code.

Commonly used directives include:

• @backingData: For sharing pre-fetched data between sibling field resolvers.
• @scope: For controlling visibility of types/fields across multi-module boundaries.
• @idOf: For type-safe Global ID handling.
• @oneOf: For enforcing union-like constraints on input objects.
• @connection: For marking Relay Connection types.
• @edge: For marking Relay Edge types.