Skip to content

Commit ba43c93

Browse files
hasparusdimaMachinasaihaj
authored
Case studies (#6349)
Co-authored-by: Dimitri POSTOLOV <[email protected]> Co-authored-by: Saihajpreet Singh <[email protected]>
1 parent 4fc54c6 commit ba43c93

34 files changed

+1246
-53
lines changed

‎.eslintrc.cjs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,9 @@ module.exports = {
234234
config: path.join(__dirname, './packages/web/docs/tailwind.config.ts'),
235235
},
236236
},
237+
rules: {
238+
'import/extensions': 'off',
239+
},
237240
},
238241
{
239242
files: 'cypress/**',

‎packages/web/docs/package.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
"name": "@hive/docs",
33
"type": "module",
44
"private": true,
5+
"imports": {
6+
"#components/*": "./src/components/*"
7+
},
58
"scripts": {
69
"build": "next build && next-sitemap",
710
"dev": "next --turbopack",

‎packages/web/docs/src/app/_meta.ts

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,15 @@ const meta: Record<string, DeepPartial<Item | MenuItem | PageItem>> = {
6060
typesetting: 'article',
6161
},
6262
},
63+
'case-studies': {
64+
type: 'page',
65+
title: 'Case Studies',
66+
theme: {
67+
sidebar: false,
68+
toc: false,
69+
breadcrumb: false,
70+
},
71+
},
6372
'oss-friends': {
6473
type: 'page',
6574
title: 'Our Open Source Friends',

‎packages/web/docs/src/app/case-studies/(posts)/layout.tsx

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
import { GetYourAPIGameWhite } from '#components/get-your-api-game-white';
2+
import { cn } from '@theguild/components';
3+
import { CaseStudiesHeader } from '../case-studies-header';
4+
import { MoreStoriesSection } from '../more-stories-section';
5+
import '../case-studies-styles.css';
6+
import { LookingToUseHiveUpsellBlock } from '../looking-to-use-hive-upsell-block';
7+
8+
// We can't use CSS Modules together with Tailwind,
9+
// because the class responsible for dark mode gets transformed
10+
// so `dark:` prefixes don't work.
11+
const ONE_OFF_CLASS_CASE_STUDIES = 'case-studies';
12+
13+
export default function CaseStudiesLayout({ children }: { children: React.ReactNode }) {
14+
return (
15+
<div className={cn(ONE_OFF_CLASS_CASE_STUDIES, 'mx-auto box-content max-w-[90rem]')}>
16+
<CaseStudiesHeader className="mx-auto max-w-[--nextra-content-width] pl-6 sm:my-12 md:pl-12 lg:my-24" />
17+
<aside className="relative mx-auto max-w-[--nextra-content-width]">
18+
<LookingToUseHiveUpsellBlock className="absolute right-2 top-4 max-lg:hidden lg:w-[320px] xl:w-[400px]" />
19+
</aside>
20+
{children}
21+
<MoreStoriesSection />
22+
<GetYourAPIGameWhite className="sm:my-24" />
23+
</div>
24+
);
25+
}

‎packages/web/docs/src/app/case-studies/(posts)/sound-xyz/page.mdx

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: 'Sound.xyz: Scaling GraphQL Infrastructure for Web3 Music Innovation'
3+
excerpt:
4+
'Sound.xyz is revolutionizing the music industry by addressing two critical challenges: the
5+
concentration of streaming revenue among top artists and the inadequate compensation per stream.'
6+
category: Music
7+
authors:
8+
- name: David Greenstein
9+
position: Co-Founder
10+
avatar: https://avatars.githubusercontent.com/u/30914691?v=4
11+
---
12+
13+
import { DocsIcon, LargeCallout } from '#components/large-callout'
14+
import { Lede } from '#components/lede'
15+
import { SmallAvatar } from '#components/small-avatar'
16+
import { CallToAction, ContactButton } from '@theguild/components'
17+
18+
<Lede>
19+
Sound.xyz is revolutionizing the music industry by addressing two critical challenges: the
20+
concentration of streaming revenue among top artists and the inadequate compensation per stream.
21+
As they scale their platform to empower artists and build stronger community connections, their
22+
technical infrastructure needs have evolved significantly, particularly in API management and
23+
service architecture.
24+
</Lede>
25+
26+
## Background
27+
28+
Sound.xyz was founded with a mission to transform the economics of music streaming. The platform
29+
aims to address two fundamental problems in the current music industry:
30+
31+
- The extreme concentration of attention, where 90% of streams go to just 1% of artists
32+
- The unsustainable economics of streaming, where artists earn only $0.003 per stream
33+
34+
The company's vision centers on creating a more equitable music ecosystem that properly values
35+
artistic content and enables artists to build sustainable careers.
36+
37+
![Sound.xyz: Discover new music and prove you were there first](./sound-xyz.webp)
38+
39+
## Challenges
40+
41+
Sound.xyz implemented a sophisticated GraphQL-based architecture with the following key components:
42+
43+
1. **Scale and Complexity**
44+
- Moved from a monolithic structure to a microservices architecture
45+
- Enabled independent service scaling and development
46+
- Maintained service autonomy while ensuring cohesive API experience
47+
2. **GraphQL Implementation**
48+
- Adopted GraphQL as the primary API layer for all clients
49+
- Implemented GraphQL stitching to combine multiple service schemas
50+
- Utilized Hive as the central source of truth for the GraphQL gateway
51+
3. **Schema Management**
52+
53+
Selected Hive as their GraphQL management platform due to:
54+
55+
- Existing integration with GraphQL Inspector
56+
- Comprehensive schema management capabilities
57+
- Built-in analytics and monitoring
58+
- Breaking change detection and prevention
59+
60+
## Implementation
61+
62+
Sound.xyz's implementation journey began with a monolithic GraphQL API that served as the foundation
63+
for their platform. As the platform grew, they systematically decomposed this monolith into
64+
microservices, implementing GraphQL stitching to maintain a unified API interface. The integration
65+
of Hive came as a natural progression, building upon their existing GraphQL Inspector implementation
66+
and providing additional tools for schema management and API monitoring. This phased approach
67+
allowed them to maintain service stability while gradually transitioning to a more scalable
68+
architecture.
69+
70+
<div>
71+
72+
> Hive gives us great developer experience and observability over our GraphQL API.
73+
74+
<cite>
75+
<SmallAvatar src="https://avatars.githubusercontent.com/u/3156233?v=4" />
76+
<span>Vignesh Hirudayakanth</span>
77+
<span>Sound.xyz</span>
78+
</cite>
79+
80+
</div>
81+
82+
## Results and Benefits
83+
84+
The implementation provided Sound.xyz with several key advantages:
85+
86+
1. **Developer Experience**
87+
- Unified schema management
88+
- Consistent API documentation
89+
- Improved development velocity
90+
2. **Operational Efficiency**
91+
- Centralized API monitoring
92+
- Automated breaking change detection
93+
- Reduced maintenance overhead
94+
3. **Platform Scalability**
95+
- Independent service scaling
96+
- Flexible architecture for new features
97+
- Improved system reliability
98+
99+
<LargeCallout
100+
icon={<DocsIcon />}
101+
heading="Automated Breaking Change Detection"
102+
variant="secondary"
103+
cta={
104+
<CallToAction variant="tertiary" href="/docs/management/projects#alerts-and-notifications">
105+
Learn More
106+
</CallToAction>
107+
}
108+
>
109+
Configure and utilize automated breaking change detection to identify and address schema changes
110+
before they impact your API consumers. Ensure seamless updates and maintain API reliability with
111+
this step-by-step guide.
112+
</LargeCallout>
113+
114+
## Lessons Learned
115+
116+
Schema Management is Critical: Centralized schema management becomes increasingly important as the
117+
number of services grows. Tool Selection Matters: Choosing Hive early provided built-in solutions
118+
for common challenges. Architecture Evolution: Starting with a monolith and gradually transitioning
119+
to microservices allowed for controlled growth.
120+
121+
<LargeCallout
122+
icon={<DocsIcon />}
123+
heading="Simplify Your Schema Management"
124+
variant="primary"
125+
cta={<ContactButton variant="secondary-inverted" />}
126+
>
127+
Effortlessly manage schemas, track versions, and automate change notifications to ensure reliable
128+
and scalable GraphQL APIs.
129+
</LargeCallout>
130+
131+
## Future Considerations
132+
133+
As Sound.xyz continues to grow, they are well-positioned to:
134+
135+
- Scale their microservice architecture further
136+
- Add new features and services independently
137+
- Support an expanding developer ecosystem
138+
- Maintain API stability while innovating rapidly
139+
140+
## Conclusion
141+
142+
Sound.xyz's implementation of a GraphQL-based architecture, managed through Hive, demonstrates how
143+
modern API management tools can support rapid growth while maintaining stability and developer
144+
experience. Their approach provides a valuable template for other organizations facing similar
145+
challenges in scaling their API infrastructure.

‎packages/web/docs/src/app/case-studies/(posts)/sound-xyz/sound-xyz.webp

268 KB
Binary file not shown.

‎packages/web/docs/src/app/case-studies/(posts)/wealthsimple/page.mdx

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
title: "Building a Unified Financial API: Wealthsimple's Hive Implementation"
3+
excerpt:
4+
'As the company scaled, the need for a robust, flexible, and efficient API architecture became
5+
paramount, leading to the adoption of GraphQL with Hive as their central API management solution.'
6+
category: Finance
7+
# We would need to go through approval to get author images. I guess we can leave this as is for now.
8+
authors:
9+
- name:
10+
position:
11+
avatar:
12+
---
13+
14+
import { DocsIcon, LargeCallout } from '#components/large-callout'
15+
import { Lede } from '#components/lede'
16+
import { SmallAvatar } from '#components/small-avatar'
17+
import { CallToAction, ContactButton } from '@theguild/components'
18+
19+
[Wealthsimple](https://www.wealthsimple.com/en-ca) is one of Canada's fastest growing financial
20+
institutions and offers a full suite of simple, sophisticated financial products. As the company
21+
scaled, the need for a robust, flexible, and efficient API architecture became paramount, leading to
22+
the adoption of GraphQL with Hive as their central API management solution.
23+
24+
## Challenges
25+
26+
The primary challenges that led Wealthsimple to seek a GraphQL solution included:
27+
28+
1. **Service Integration Complexity**
29+
30+
- Managing a distributed architecture with many microservices
31+
- Need for comprehensive usage analytics beyond basic performance monitoring
32+
- Coordinating API changes across multiple development teams
33+
- Ensuring consistent performance regardless of customer profile
34+
35+
2. **Development Workflow**
36+
37+
- Lack of visibility into API usage patterns
38+
- Difficulty in tracking deprecated field usage
39+
- No systematic way to validate schema changes
40+
- Coordinating between multiple client applications (mobile and web)
41+
42+
## Architecture
43+
44+
### GraphQL Gateway
45+
46+
At the heart of the system lies a centralized GraphQL gateway that serves as the primary entry point
47+
for all client applications. Built with TypeScript and Node.js, this gateway acts as an intelligent
48+
router, orchestrating requests across the service landscape. The gateway implements
49+
[schema stitching](https://the-guild.dev/graphql/stitching) to unify microservice schemas into a
50+
cohesive API surface.
51+
52+
### Service Layer
53+
54+
The underlying service layer comprises domain-specific services, representing different areas of
55+
Wealthsimple's financial ecosystem. Most services are built in Ruby, with a small subset using other
56+
technologies. These services use a mixed architecture approach, where some endpoints expose GraphQL
57+
interfaces while others maintain REST APIs. To seamlessly integrate REST services, the gateway
58+
utilizes Apollo data sources, ensuring consistent data access patterns. The team has also developed
59+
specialized components, including a custom Spring bean for reporting usage metrics to GraphQL Hive.
60+
61+
<div>
62+
> Hive enables Wealthsimple to build flexible and resilient GraphQL APIs. The GitHub integration
63+
provides feedback in a format developers are familiar with and conditional breaking changes enable
64+
us to focus our discussion on schema design rather than maintenance. Hive empowers us to
65+
confidently evolve our schemas by ensuring seamless API updates, detecting potential breaking
66+
changes, and guiding developers.
67+
</div>
68+
69+
## Implementation
70+
71+
The implementation focused on two key areas:
72+
73+
1. **Usage Analytics Integration**
74+
75+
- Implemented complementary tracking alongside existing Datadog setup
76+
- Enhanced GraphQL usage monitoring capabilities:
77+
- Client-specific query tracking
78+
- Detailed operation body analysis
79+
- Real-time usage statistics
80+
81+
2. **Schema Validation System**
82+
83+
- Established global policy for schema changes
84+
- Implemented 30-day field usage monitoring
85+
- Integrated real-time developer feedback system
86+
- Set up automated validation checks for breaking changes
87+
88+
## Results & Benefits
89+
90+
The implementation has delivered several significant benefits:
91+
92+
1. **Enhanced Development Workflow**
93+
94+
- Data-driven decision making for schema changes.
95+
- Prevented potentially breaking changes through usage analysis.
96+
- Improved developer confidence in schema modifications.
97+
98+
2. **Operational Improvements**
99+
100+
- Better visibility into API usage patterns.
101+
- Reduced risk of breaking changes.
102+
- More efficient schema management.
103+
104+
<LargeCallout
105+
icon={<DocsIcon />}
106+
heading="Comprehensive Query Insights"
107+
variant="secondary"
108+
cta={
109+
<CallToAction variant="tertiary" href="/docs/dashboard/insights">
110+
Learn More
111+
</CallToAction>
112+
}
113+
>
114+
Get a detailed view of all GraphQL operations executed by your consumers, including performance
115+
metrics and total counts. Click on any specific query to explore the full list of fields and
116+
arguments used in the operation.
117+
</LargeCallout>
118+
119+
## Lessons Learned
120+
121+
1. **Schema Validation Impact**
122+
123+
Schema validation has helped Wealthsimple's API development process by enabling data-driven
124+
decisions based on actual usage patterns. This shift from guesswork to quantifiable insights has
125+
allowed teams to confidently evolve the API while maintaining stability for existing clients.
126+
127+
2. **Integration Considerations**
128+
129+
Cross-platform integration has positioned Wealthsimple as an active contributor to the
130+
open-source community, where they now maintain the official
131+
[GraphQL Hive Ruby client](https://github.com/rperryng/graphql-ruby-hive?tab=readme-ov-file#graphql-hive-graphql-ruby-integration).
132+
This commitment to open-source development not only supports their own cross-platform needs but
133+
also benefits the broader GraphQL ecosystem. Their experience demonstrates the importance of both
134+
consuming and contributing to open-source tools while building a robust financial platform.
135+
136+
## Future Plans
137+
138+
1. **Schema Registry Migration**
139+
140+
Wealthsimple plans to transition away from their existing git-ops system in favor of Hive's
141+
comprehensive schema registry feature. This strategic move will modernize their schema management
142+
process by providing a centralized, automated system for schema validation and distribution. This
143+
migration represents a key step in Wealthsimple's broader initiative to enhance their API
144+
infrastructure and developer experience.
145+
146+
2. **Security Infrastructure Enhancement**
147+
148+
Wealthsimple is implementing
149+
[Hive's App Deployments feature](https://the-guild.dev/graphql/hive/docs/schema-registry/app-deployments)
150+
to optimize performance and track API usage against app versions. This solution will restrict API
151+
access to predefined queries only and implement a query hash system for network optimization.
152+
153+
3. **Gateway Evolution**
154+
155+
Wealthsimple is improving its API gateway infrastructure by focusing on migrating from their
156+
current Apollo server with schema stitching to Hive Gateway. Having already tested
157+
[GraphQL Yoga](https://the-guild.dev/graphql/yoga-server) in staging with
158+
[promising performance gains](https://the-guild.dev/graphql/yoga-server/docs/comparison#better-runtime-performance),
159+
the team is now working on adopting Hive Gateway to enable a gradual transition to
160+
[federation](https://the-guild.dev/graphql/hive/federation). This approach will allow teams to
161+
maintain ownership of their schemas while enabling a methodical, type-by-type migration from the
162+
existing stitched schema setup to a federated architecture.
163+
164+
<LargeCallout
165+
icon={<DocsIcon />}
166+
heading="Elevate Your GraphQL Journey"
167+
variant="primary"
168+
cta={<ContactButton variant="secondary-inverted" />}
169+
>
170+
Transform your API infrastructure like Wealthsimple. Whether it's migrating to a centralized
171+
schema registry, enhancing security, or evolving your gateway architecture, our tools and
172+
expertise can help you achieve your goals efficiently.
173+
</LargeCallout>
174+
175+
## Conclusion
176+
177+
Wealthsimple's implementation of GraphQL with Hive has proven to be a successful strategic decision,
178+
providing enhanced visibility, improved development workflows, and a solid foundation for future
179+
scaling. The company's positive experience with the platform has led to expanded usage plans and
180+
continued investment in the GraphQL ecosystem. The gradual, thoughtful approach to migration and
181+
feature adoption has enabled the team to maintain stability while advancing their technical
182+
capabilities.

‎packages/web/docs/src/app/case-studies/_meta.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
export default {
2+
'*': {
3+
display: 'hidden',
4+
},
5+
};

0 commit comments

Comments
 (0)