Step-by-Step Teaching

Step 1: Understanding the Core Problem

Why Does This Problem Exist?

Imagine a large company like Airbnb with hundreds of engineering teams:

Team A → manages listings data
Team B → manages user profiles
Team C → manages payments
Team D → manages reviews

Without a unified system, every client (mobile app, web app) must know:

• Which server to call
• What format each server expects
• How to combine data from multiple servers

🔑 Key Concept: This creates chaos at scale — hard to discover APIs, inconsistent interfaces, no central governance

---

Step 2: The Solution — A Central Schema

A central schema provides ONE unified interface:

Client App
    ↓
[Single GraphQL Interface]
    ↓         ↓         ↓
Listings   Users   Payments

Benefits of Central Schema:

The New Problem This Creates:

❗ A central schema only works if it can evolve quickly

If ONE central team owns everything:

• They become a bottleneck
• Domain experts lose autonomy
• Schema evolves slowly

The real challenge:

Give teams autonomy over their domain
        +
Preserve coherence of the shared schema

---

Step 3: How Viaduct Solves This — Multi-Tenancy

Viaduct's answer is multi-tenancy through modules:

[Shared Viaduct Runtime]
    ├── Module A (Listings Team)
    ├── Module B (Payments Team)
    ├── Module C (Reviews Team)
    └── Module D (Users Team)

How a Team Contributes:

Step 1: Create a directory for their module
Step 2: Define their SDL (Schema Definition Language)
Step 3: Write their resolvers
Step 4: Ready to serve ✓

What Teams DON'T Need to Do:

• ❌ Set up a separate GraphQL server
• ❌ Manage router composition
• ❌ Become GraphQL infrastructure experts

🔑 Key Principle: Teams focus on domain logic. The platform handles execution, scaling, and integration

---

Step 4: Viaduct vs GraphQL Federation

This is a critical comparison to understand:

GraphQL Federation Approach:

Team A → runs Server A (subgraph)
Team B → runs Server B (subgraph)
Team C → runs Server C (subgraph)
         ↓
   [Federation Router]
         ↓
   Unified Graph

Viaduct Approach:

Team A → writes Module A
Team B → writes Module B  →  [Shared Viaduct Runtime]
Team C → writes Module C
                ↓
         Unified Graph

Side-by-Side Comparison:

🔑 Core Distinction:

• "Federation distributes development by distributing servers"
• "Viaduct distributes development by distributing modules"

---

Step 5: How They Work Together

Viaduct and Federation are not competitors — they are complementary:

[Federation Router]
    ├── Viaduct Instance 1 (hosts 50 related modules)
    ├── Viaduct Instance 2 (hosts 40 related modules)
    └── Other Subgraph Servers

Why This Matters at Scale:

Without Viaduct:  500 teams = 500 servers to manage
With Viaduct:     500 teams = 10 Viaduct instances (each hosting ~50 modules)

✅ Fewer servers to operate while maintaining team autonomy

---

Step 6: The 1.0 Stability Commitment

Understanding versioning signals matters for engineers:

API Stability Annotations:

@StableApi    → Safe to use, no breaking changes
@ExperimentalApi → May change, use with caution  
@InternalApi  → Do not use externally

What "1.0" Means in Practice:

• Binary compatibility validator runs in CI
• Published to Maven Central
• Automated releases
• Community-driven RFC process (not just internal decisions)

---

Concept Summary Map

PROBLEM: Decentralized development of a central schema
         ↓
SOLUTION: Viaduct (multi-tenant module system)
         ↓
HOW:     Teams write modules → shared runtime executes
         ↓
VS:      Federation (teams run servers → router composes)
         ↓
TOGETHER: Viaduct instances act as Federation subgraphs
         ↓
RESULT:  Scalable, autonomous, unified data API

---

Quick Self-Check Questions

1. What problem does Viaduct solve?

   Decentralized development of a central GraphQL schema

2. What is the key difference between Viaduct and Federation?

   Federation distributes via servers; Viaduct distributes via modules

3. Why can't a single central team own the entire schema?

   They become a bottleneck; domain experts lose autonomy; schema evolves too slowly

4. How do Viaduct and Federation work together?

   Viaduct instances serve as subgraphs within a federated architecture, reducing total server count

5. What does a team need to do to contribute to Viaduct?

   Create a module directory, define SDL, write resolvers — no server setup required