DEV Community: IlyasM

Quick prototyping with GRAND stack – part 3

IlyasM — Thu, 15 Oct 2020 12:10:31 +0000

Quick prototyping with GRAND stack: part 3

Part 1 – Product introduction, tech spec and graph model.
Part 2 - Apollo Graphql server and neo4j-graphql-js
Part 3 - Apollo client and React

In the previous part we set up our graphql server with neo4j-graphql-js. Here we will consider how apollo-client can add a productivity boost by simplifying data management in your React applications.

Data management made simple

Apollo client is a great data management solution as it covers all the possible data requirements of a modern spa. Let's consider how helplful it is for our product. Here is the react component for managing the home screen of our application – potential collaboration candidates.

import React from "react";
import { useQuery, gql } from "@apollo/client";
import { Viewer } from "../generated/Viewer";
import FireCard from "./FireCard";
import { useHistory } from "react-router-dom";
import NoResults from "./NoResults";
import Loading from "./Loading";
export const GET_USER = gql`
  query Viewer($id: ID!) {
    viewer(userId: $id) {
      userId
      matchCandidates(first: 10) {
        score
        user {
          name
          bio
          imageUrl
          userId
          skills {
            name
          }
        }
      }
    }
  }
`;

const Fire: React.FC<{ id: string }> = (props) => {
  const { loading, data, error, refetch, client } = useQuery<Viewer>(GET_USER, {
    variables: { id: props.id },
    notifyOnNetworkStatusChange: true,
  });
  const history = useHistory();

  // once viewer made a decision about (dis)liking, update the cache by removing cards viewer dis(liked)
  // pass function to FireCard component, which runs (dis)like mutation
  const update = (id: string) => {
    client.writeQuery({
      query: GET_USER,
      variables: { id: props.id },
      data: {
        viewer: {
          ...data?.viewer,
          matchCandidates: data?.viewer.matchCandidates.filter(
            (match) => match.user.userId !== id
          ),
        },
      },
    });
  };

  // refetch when swiped on all suggested candidates
  React.useEffect(() => {
    if (data && data.viewer.matches.length < 1) {
      refetch();
    }
  }, [data, refetch]);

  if (loading) {
    return <Loading>Loading potential candidates...</Loading>;
  }
  if (error || !data) {
    return (
      <h1 style={{ textAlign: "center", height: "100vh" }}>
        Try reloading the page...
      </h1>
    );
  }

  const { viewer } = data;

  if (viewer.matches.length < 1) {
    return (
      <NoResults
        buttonText={"Update preferences"}
        description="We don't have any candidates for you now. Try updating your preferences."
        action={() => history.push("/profile")}
      />
    );
  }

  return (
    <section className="f-col-center">
      <h1>Best candidates for {viewer.name}</h1>
      {viewer.matchCandidates.map((item) => (
        <FireCard
          key={item.user.userId}
          update={update}
          viewerId={props.id}
          score={item.score}
          {...item.user}
        />
      ))}
    </section>
  );
};
export default Fire;

A lot is going on there. But let's start from the very beginning. At first, we define our graphql query GET_USER to specify our data requirements for the component. In part two, we had the matchCandidates field on type User, here we are requesting that data so our client can show potential match candidates. Apollo-client ships with a bunch of helpful react hooks to take advantage of the new react hooks functionality. First line of our function component calls useQuery hook and gets back convenient properties to manage the state of the query. Next, we have an update function to update our cache after the like or dislike has been made. Apollo-client has a nice cache.modify api which can be specified in the update argument of the mutation. Here is the extract from their docs:

const [addComment] = useMutation(ADD_COMMENT, {
  update(cache, { data: { addComment } }) {
    cache.modify({
      fields: {
        comments(existingCommentRefs = [], { readField }) {
          const newCommentRef = cache.writeFragment({
            data: addComment,
            fragment: gql`
              fragment NewComment on Comment {
                id
                text
              }
            `,
          });
          return [...existingCommentRefs, newCommentRef];
        },
      },
    });
  },
});

The reason I am specifying an update function in the parent component is that I have 2 mutations, like and dislike, so it is less cumbersome in the FireCard component:

const ADD_LIKE = gql`
  mutation AddLike($from: ID!, $to: ID!) {
    like(from: $from, to: $to) {
      matched
      matchId
      email
    }
  }
`;
const DISLIKE = gql`
  mutation AddDislike($from: ID!, $to: ID!) {
    dislike(from: $from, to: $to)
  }
`;

const FireCard: React.FC<Props> = ({
  imageUrl,
  bio,
  name,
  skills,
  userId,
  score,
  viewerId,
  update,
}) => {
  const history = useHistory();
  const variables = { from: viewerId, to: userId };
  const [addLike, { loading }] = useMutation<AddLike>(ADD_LIKE, {
    notifyOnNetworkStatusChange: true,
  });
  const [addDislike, { loading: disLoading }] = useMutation<AddDislike>(
    DISLIKE,
    {
      notifyOnNetworkStatusChange: true,
    }
  );
  const dislike = async () => {
    await addDislike({ variables });
    update(userId);
  };

  const like = async () => {
    const result = await addLike({ variables });
    const matchId = result.data?.like?.matchId;

    if (matchId) {
      // go to match
      message.success(
        `Great! You matched with ${name}! Say hi, by adding your first track.`
      );
      history.push(`/matches/${matchId}`);
    }
    update(userId);
  };

  return (
    <Card
      hoverable
      className={"card"}
      style={{
        cursor: "auto",
        marginTop: 20,
      }}
      actions={[
        disLoading ? (
          <Spin indicator={antIcon} />
        ) : (
          <DislikeFilled
            onClick={dislike}
            style={{ fontSize: 22 }}
            key="dislike"
          />
        ),
        loading ? (
          <Spin indicator={antIcon} />
        ) : (
          <LikeFilled style={{ fontSize: 22 }} onClick={like} key="like" />
        ),
      ]}
    >
      <Meta
        avatar={<Avatar size={50} src={imageUrl || getRandomImage(name)} />}
        title={name}
        description={bio}
      />
      <p style={{ marginTop: 20, color: "rgb(150,150,150)" }}>
        <span>{score} overlapping</span>
      </p>
      <div
        style={{
          borderTop: "1px solid rgb(200,200,200)",
        }}
      >
        <h4 style={{ marginTop: 20 }}>I am skilled at</h4>
      </div>
      <Tags items={skills} />
    </Card>
  );
};
export default FireCard;

This is really what is great about apollo – it takes care of your data fetching and management needs in an intuitive, easy to grasp way. No more of your cache management redux code or fetching sagas' testing. Apollo just works and takes a burden of maintaining and testing remote-data synchronization logic away from you. Just concentrate on your application requirements and not on the common data fetching and management setup!

To further illustrate this, one of the use cases of the application is to be able to specify preferences to be matched on. Once you choose your preferences, the application should show you a new candidates list in our home screen.

Originally, I had a useEffect hook set up in the Fire component and had some logic for refetching data on the preference update. But then I thought, this use case is so common, what does apollo have for that? And as expected, they have a convenient refetchQueries api which amounted to adding our GET_USER query to the refetch list, once the viewer updated their preferences:

const [batchPrefer, { loading: mutationLoading }] = useMutation<Batch>(
  BATCH_PREFER,
  {
    notifyOnNetworkStatusChange: true,
    refetchQueries: [{ query: GET_USER, variables: { id: props.id } }],
    awaitRefetchQueries: true,
  }
);

This is the running theme of GRAND stack, let great technologies abstract away common tasks, so you can concentrate on your business requirements. Don't spend your precious brain cycles on boilerplate, delegate this to talented engineering teams at neo4j and apollo and ship your ideas faster.

Building the product

In these series I went through building a GRAND stack application which is now live. Originally, after specifying the tech spec, I timeboxed it to within a weekend after having my graphql server powered by neo4j graph working in 2 hours. But then, spend the week drawing components using tailwindcss, after finally giving up and switching to ant design, which is a great solution for quick prototyping. Al in all, I went 2 weeks over my original expectation, mainly due to ui concerns. The motivation for this product and building in public came from https://www.indiehackers.com/ and me wanting to learn a graph technology. Now I am hoping to find co-founders for this product through its users.

Quick prototyping with GRAND stack – part 2

IlyasM — Thu, 15 Oct 2020 07:35:12 +0000

Quick prototyping with GRAND stack: part 2

Part 1 – Product introduction, tech spec and graph model.
Part 2 - Apollo Graphql server and neo4j-graphql-js
Part 3 - Apollo client and React

In the first part of the series we introduced our product, our graph for the tech spec and discussed why you should consider GRAND stack for quick prototyping. In this part I will show you how to quickly build a graphql server using apollo server and neo4j-graphql-js. This post assumes some familiarity with graphql server setups.

Graphql server with neo4j-graphql-js

The main benefit of neo4j-graphql-js is that it delegates writing your own graphql resolvers to cypher queries. It makes neo4j the work horse of your business logic. Additionally, it takes care of pagination, filtering and the dreaded N+1 query problem. Let's take a look at an example – our type definitions in schema.graphql:

type User {
  userId: ID!
  name: String
  email: String!
  matchCandidates: [UserWithScore!]!
    @cypher(
      statement: """
      MATCH (this)-[:PREFERS]->()<-[:PREFERS]-(candidate:User)
      WHERE NOT EXISTS((this)-[:LIKES|:DISLIKES]->(candidate))
      WITH candidate, COUNT(*) AS score ORDER BY score DESC
      RETURN {userId:candidate.userId, score:score}
      """
    )
  matchedWith: [Match!]! @relation(name: "MATCHED", direction: "OUT")
}

type Match {
  matchId: ID!
  date: Date!
  createdAt: Date!
  users: [User!]! @relation(name: "MATCHED", direction: "IN")
  tracks: [Track!]! @relation(name: "HAS", direction: "OUT")
}

type Mutation @isAuthenticated {
  like(from: ID!, to: ID!): LikeResult
    @neo4j_ignore
    @cypher(
      statement: """
      MATCH (n:User {userId:$from}),(o:User {userId:$to} )
      OPTIONAL MATCH (n)<-[r:LIKES]-(o)
      MERGE (n)-[:LIKES]->(o)
      WITH n,o,r
      CALL apoc.do.when(r IS NOT NULL,
      'MERGE (n)-[:MATCHED]->(m:Match { matchId:apoc.create.uuid(),createdAt:datetime()})<-[:MATCHED]-(o) RETURN {matchId:m.matchId, matched:true, email:o.email} as result',
      'RETURN {matched:false} as result',
      {n:n, o:o}
      ) YIELD value
      RETURN value.result
      """
    )
  addTrack(userId: ID!, matchId: ID!, type: String!, desc: String!): Track!
    @cypher(
      statement: """
      MATCH (n:User {userId:$userId}), (m:Match {matchId:$matchId})
      MERGE (n)-[:ADDED]->(t:Track {trackId:apoc.create.uuid(), type:$type,description:$desc, matchId:m.matchId, createdAt:datetime()})
      MERGE (m)-[:HAS]->(t)
      return t
      """
    )
}

Neo4j-graphql-js ships with a few helpful graphql schema directives that allow the above code:

@cypher to write our neo4j queries directly in our typedefs.
@relation to specify fields by leveraging our graph relations.
@neo4j_ignore to specify a custom resolver.
@isAuthenticated to provide authentication capabilities.

Our apollo server:

const resolvers = {
  Mutation: {
    like: async (obj, args, context, info) => {
      const result = await neo4jgraphql(obj, args, context, info);
      if (result.email) {
        sendEmail(result.email);
      }
      return result;
    },
  },
};
const server = new ApolloServer({
  schema: makeAugmentedSchema({
    typeDefs,
    resolvers,
    config: {
      auth: { isAuthenticated: true },
    },
  }),
  context: ({ req }) => ({
    req,
    driver,
  }),
});

In those 2 code blocks above we actually specified 90% of our api server. In the previous part we went through matchCandidates field on type User. Now, let's go over the like mutation line by line. First we see @neo4j_ignore, it let's us specify our custom resolver in the second code block for the purpose of adding logic not directly related to our graph (sending email in this case). Next is the cypher query. Line by line:

Find two users by id – me and the user I like.
Check if the other user already liked me.
Create a like relation between me and other user.
Collect variables specified in the above lines, me, other user and their potential like of me.
Apoc procedure to do some branching.
- Apoc is a library of many helpful procedures and algorithms to make our graph developer experience better.
- In our procedure we check if the other user has already liked us, if they have we create a match and provide email in the result to notify the other user that we matched. Return false otherwise.

All the heavy lifting is done by makeAugmentedSchema, which auto-generates queries, mutations, filtering and pagination. Here is a great write up on how makeAugmentedSchema avoids N+1 query problem. Basically, it traverses the graph structure given in the resolveInfo object and combines every field's query as a subquery for one query on that type.

Takeaways

The key feature of GRAND stack is that – once you are finished with modelling your business requirements with a graph – to get your business logic layer set up is a matter of writing out a few type definitions with a declarative cypher query language, because graphs lend themselves quite naturally to a variety of complex requirements.

To better illustrate this point. Let's say we want to add a 3-way match requirement, i.e if Alice has a mutual like with Bob and Claire, and Bob and Claire have a mutual like between them, create a 3-way match card. This is how easily this requriment is satisfied on the backend:

type User{
  ...
  threeWayMatches:[[User!]]!
    @cypher(statement:"""
    MATCH (u1:User)-[:MATCHED*2]-(this)-[:MATCHED*2]-(u3:User)
    WHERE EXISTS((u1)-[:MATCHED*2]-(u3))
    RETURN u1,u3
    """)
}

In just 3 lines we satisfied a non-trivial requirement which would let us justify the following product slogan: "For every Harry we will help find Hermione and Ron".

Our graph

The productivity of setting up graphql servers with neo4j is remarkable. I got a working server for matchandhack.com in 2 hours after fiddling with the arrow tool and making my graph (see the image above). In the next part we will see how apollo-client simplifies data management on the front-end to get us even closer to the LAMP stack level of productivity.

Quick prototyping with GRAND stack - part 1

IlyasM — Wed, 14 Oct 2020 12:19:37 +0000

Quick prototyping with GRAND stack: part 1

Part 1 – Product introduction, tech spec and graph model.
Part 2 - Apollo Graphql server and neo4j-graphql-js
Part 3 - Apollo client and React

In these series I will go through building a simple web application using the latest and greatest on the web - the GRAND stack. What does it stand for? Graphql, React, Apollo and Neo4j Database. Why should you consider using this stack for your next project? Mainly, for much shorter development cycles, which gets you (here Michael Siebel describes what goes into building an MVP) a better chance to find a product market fit.

The product

The application we are going to develop is a peer matching application. In short – Tinder for indie hackers. This application will provide peer matching opportunities based on users' preferences for pop-culture genres, their skill level and their collaboration goals. If you want to do a mock up coding interview session, find a co-founder, a study buddy, a friend or study one of coursera courses with somebody you would login and setup your profile:

After that you can see those who have a similar set of preferences and thus are a better fit for you:

If you like them and they like you back the match will be created where you can set up collaboration routines:

You can watch the ux flow here.

The tech spec and graph model

It is always a good idea to have a tech spec before you start building something. Here is an example one for this product. For the modelling part the accepted flow for neo4j community is using the arrow tool at http://www.apcjones.com/arrows/#. Which is a great resource for modelling your data according to the tech spec you specified. Here is the one for this product:

What is great about graphs is that they are natural to think about and easy to model our business requirements in. As you can see the application flow is apparent from the graph:

Users can like or dislike each other
Create tracks and comments
Have preferences for goals, skills and pop-culture genres

Neo4j ships with an intuitve cypher query language which let's you specify your queries in a natural ASCII-Art syntax that resembles our graph. Here is an example one for the main screen of our product – best collaboration candidates for our user:

MATCH (u:User{userId:"1"})-[:PREFERS]->()<-[:PREFERS]-(candidate:User)
WHERE NOT EXISTS((u)-[:LIKES|:DISLIKES]->(candidate))
WITH candidate, COUNT(*) AS score ORDER BY score DESC
RETURN {userId:candidate.userId, score:score}

Let's go line by line. First line: find a user by id, who prefers the same thing as the candidate user. The curly braces surrounded by [:PREFERS]->()<-[:PREFERS] could stand for either a genre, a goal or a skill. Second line: exclude those candidates which the user already liked or disliked. Third line: count the number of preference paths and order candidates by this count. Fourth line: return these candidates with count as a score. This simple query straight away satisfies one of the main requirements for our product - the potential matches requirement in the tech spec!

What is great about using neo4j as your data store is its richness to model your business requirements straightaway without the pain of modelling your sql store to satisfy your requirements. Additionally, neo4j-graphql-js integration further improves developer experience by delegating the setup of your graphql server to neo4j queries. I shall explore it in more detail in part 2.