Documentation revamp 📖 ✨ (umbrella issue)

[charlypoly]

• Index page (Project purpose and vision /w illustrations, Performances expectations)
• Getting Started
  • Overview (Concepts, Glossary)
  • Installation
  • Our first Mesh Gateway (simple tutorial: one source, simple transforms + next steps overview → guides)
  • Combine multiple Sources
  • Handle Sources with no definition (additional resolvers/typeDefs vs jsonSchema handler with samples)
  • Customize the Mesh server (Envelop, cache, included server vs a custom server)
  • Deploy a GraphQL Mesh gateway (Serverless, Mesh artifacts, docker, etc...)
  • Comparison table → “Building Unified Schema Gateway experience”

#3731, #3779

---

• Guides
  • Extending the Unified Schema (additionalResolvers guide)
  • Configure GraphQL Code Generator with Mesh (configuration, resolvers type safety)
  • Performances best practices (batching, etc)
  • Advanced Transforms: root-level, source-level and order
  • Error handling
  • File upload
  • Live Queries
  • Subscriptions & Webhooks

#3824

---

• Handlers reference
• Transforms reference
  • → review and update
  • update JSON Schema handler documentation (@TuvalSimha, @charlypoly)

⚠️ → API reference on a dedicated page + top nav link (different from documentation)

→ should we drop the API reference?

[charlypoly]

Examples revamp:

Services

Books API (OpenAPI)

• GET /books
• GET /books/:id
• GET /books/categories

Authors API (gRPC)

• list
• one

Stores (GraphQL)

• stores Query
• bookSells Query

---

Mesh use-cases

Getting started > Build your first Gateway

• Books APIs -> list -> books Query

How to > Combine multiple Sources

Target Query:

query bestSellersByStore {
  stores {
    location
    name
    booksells {
      name
      categories {
        name
      }
      authors {
        name
      }
    }
  }
}

Guides > Performances

Use batching and query batching for:

query bestSellersByStore {
  stores {
    location
    name
    booksells {
      name
      categories {
        name
      }
      authors {
        name
      }
    }
  }
}

Guides > Extending the Unified Schema

Target Query:

query bestSellersByStore {
  bestSellers { # across stores
    name
    categories {
      name
    }
    authors {
      name
    }
  }
}