This is the tale of how we, at Balsamiq, rolled out our new web-app, from greenfield to production. A real-world application with real-time collaboration, built using Relay, Redux, React-rendered html emails, node.js, Redis, etc., running on AWS using Convox. Even at small/medium scale, if you're serious about building a good product you will eventually have to build a complex stack. I will share the details of the services we use, how we make them fit together and what we learned in the process.

1. GraphQL in production
Stefano Masini
@stefanomasini
16 May 2017
https://creativecommons.org/licenses/by-nc-sa/4.0/

2. GraphQL
• Alternative to REST
• Space efficient in the network
• Nice way to describe the UI data requirements
• Nice way to organize code on the server

3. GraphQL
query {
loggedUser {
name
avatarUrl
}
}
Request
{
loggedUser: {
name: "Stefano Masini",
avatarUrl: "http://..."
}
}
Response

4. GraphQL
Query
Read
Mutation
Write
Subscription
Server-side events

5. Relay
GraphQL
• Component data requirements
• Communication
• Caching
Transport layer
Application state management
Modern

11. Balsamiq Cloud
• 26k LOC + actual editor: 130k LOC
• ~ 30 external dependencies (non-trivial ones)
→ 115 deps in package.json
→ 860 mods in node_modules
• ~200 React Components (spread in 55 files)
• 32 GraphQL mutations
• 25 events
• 120 integration tests → ~80% coverage (server-side)

12. graphql Other HTTP
operations
mutationsschema
Other HTTP
Redis
Database
notifications
mail
payment
processor
Architecture
AWS / Convox

13. Hexagonal architecture
adapter
adapter adapter
adapter
adapter
adapter
19 adapters in Cloud
• authentication
• cache
• database
• logging
• mailing
• pub-sub
• routing
• ...
→ Dependency injection
→ GraphQL context

14. “You wanted a banana
but what you got
was a gorilla
holding the banana
and the entire jungle.”
Joe Armstrong
Dependencies

15. const ProjectType = new GraphQLObjectType({
name: 'Project',
interfaces: [nodeInterface],
fields: () => ({
id: globalIdField('Project', project => `${project.id}-${project.siteId}`),
properties: {
type: ProjectPropertiesType,
description: 'The project properties that live on the BAS',
resolve: resolveWithLogger('properties', (project, args, { basAdapter, logger }) =>
basAdapter.getProjectProperties(project.id, project.siteId, logger)),
},
lastModified: { type: GraphQLInt, },
mockupCount: { type: GraphQLInt, },
publicView: { type: GraphQLBoolean },
users: {
type: UsersInProjectConnection,
description: 'The users (with roles) belonging to this project.',
resolve: resolveWithLogger('users', (project, args, {db}) =>
connectionFromPromisedArray(
db.queryUsersInProjectByProjectId(project.id), args)),
},
}),
});
A type definition

16. export default function({SiteType}) {
return buildMutationDefinition({
operationName: 'changeSiteName',
inputFields: {
siteId: { type: new GraphQLNonNull(GraphQLInt) },
name: { type: new GraphQLNonNull(GraphQLString) },
},
outputFields: {
site: {
type: SiteType,
resolve: ({siteId}, _, {db, loggedUser}) => db.querySiteById(siteId),
},
},
});
}
A mutation definition
naming convention
js_src
! mutations
! changeSiteName.js
...
! operations
! changeSiteName.js
...
Type definition
Implementation
(resolver)

17. An operation
export default function ({db, siteId, name, logger, notificationCentral,
subscriptionsManager, loggedUser, cache, whenFinished}) {
logger.info('performing operation: changeSiteName');
return db.withTransaction(async function () {
let userInSite = await db.queryUserInSiteById(siteId, loggedUser);
if (!userInSite) {
throw new ErrorWithInfo('User does not belong to site', {
detail: `User ${loggedUser.id} not in site ${siteId}`,
code: 'RENAME_SITE_USER_NOT_IN_SITE'
});
}
if (!userInSite.isSiteOwner()) {
throw new ErrorWithInfo('User is not site owner', {
detail: `User ${loggedUser.id} is not owner of site ${siteId}`,
code: 'RENAME_SITE_USER_NOT_SITE_OWNER'
});
}
let site = await db.changeSiteName(siteId, name);
...
await cache.storeSite(site);
await db.addHistoryLine(changeSiteName(siteId, name, loggedUser));
whenFinished(() => {
notificationCentral.notifySiteNameChanged(siteId, name, logger);
});
return {siteId};
});
}

18. Error management
1. A simple text for the user
• Indicate the next step
2. A detailed text for the server logs
• To help debug the issue
3. A unique error code
• To pinpoint the snippet of code
throw new ErrorWithInfo('User does not belong to site', {
detail: `User ${loggedUser.id} not in site ${siteId}`,
code: 'RENAME_SITE_USER_NOT_IN_SITE'
});

19. Reactivity

22. 1. Overfetching
mutation
changeUserAvatar
Client Server
event on
channel: Application
forceFetch ALL

23. 2. Specific events
mutation
changeUserAvatar
Client Server
event: userAvatarChanged
channel: Application
forceFetch
UserAvatarComponent

24. 3. Narrow channels
mutation
changeUserAvatar
Client Server
channel: User
event: userAvatarChanged
forceFetch
UserAvatarComponent

25. A hairy mess

27. channel user-me
channel user-23
channel user-42
channel site-4
changeUserAvatar
→channel user-x
changeUserName
→channel user-x
changeUserName
→channel user-x
→channel site-y
Frontend
Backend

28. Reactivity
• Relay Classic: no solution out of the box
• Pub-Sub + forceFetch: a solution but inefficient
• Relay Modern and Apollo: GraphQL Subscriptions
• Live queries: promising, but still open discussion
inherent complexity, deal with it

29. • dataloader
• https://github.com/facebook/dataloader
• makes GraphQL go O(n) → O(log n)
• ad-hoc caching
• Redis
• Tied to database access
• Ripples through all mutations
• Transactionality
Efficient data access

30. Testing
DB
Redis Mailing
Notifications
GraphQL
request
Test start
check results
check mocked
environment
Test runner Server
Regenerate DB
setup A
setup B
setup C
GraphQL request
serve request
cleanup C
cleanup B
cleanup A
Test end
120 tests in < 30 seconds
200 ms per test

31. Your cool new app

32. Naming conventions
Default behaviours
ORM
Boilerplate
Automagic caching
Explicit configuration
plain SQL
ad-hoc caching
Cool
Advanced
Productive
Repetitive
Uninteresting
Unsurprising
Predictable
SAFEMAGIC

33. Be cool, but play safe
Stefano Masini
@stefanomasini
16 May 2017
Y U NO
FEEDBACK