8 Developers Guide

Jordan Knott edited this page 2021-01-05 16:51:42 -06:00

Table of Contents

• Setting up your development environment (Linux)
• Requirements
• Frontend
• Tools used
• Directory structure
• Backend
• Tools used
• Directory structure
• GraphQL schemas
• Database Access
• Running in development mode
• Seeding the database

Setting up your development environment (Linux)

Requirements

• NodeJS & Yarn
• Golang 1.15+
• Python 3+ & Pipenv (for pre-commit hooks)
• gqlgen
• mage (can use the cmd/mage/main.go as an alternative to installing mage globally)

Frontend

Tools used

• graphql-codegen for generating typescript types from graphql queries

Directory structure

All code for the frontend can be found in the frontend directory.

src/
  App/ # folders other than shared that are directly underneath `src` are for top level modules
   index.tsx # top level modules contain the both components from `shared/components` and the apollo-graphql queries
  shared/ # code that is shared between top level modules
    components/
      Button/
        index.tsx # contains component code
        Styles.ts # contains styled component declarations
    graphql/ # contains graphql queries and mutations that are converted to typed code through `yarn generate`
    constants/ # const variables that are used in many places
    icons/ # SVG icons - all icons use a base `Icon` and are exported through the index.ts file
    utils/ # for random helpers
     accessToken.ts # tools for interacting with accessToken (the token is stored in a global variable in this file
     cache.ts # contains helper method for interacting with apollo cache
     draggables.ts # contains helper methods for interacting with draggables & droppables (react-beautiful-dnd)
     sorting.ts # the business logic for sorting tasks
     styles.ts # helper mixins and variables for styling components

Backend

Tools used

• sqlc for converting SQL query files into Golang code (1.6+ required)
• gqlgen for converting graphql schema files into Golang code

Directory structure

cmd/
  taskcafe/
    main.go # entry point for taskcafe - calls commands.Execute()
frontend/ # the React frontend code lives here
internal/ # all business logic lives here
  auth/ # code for interacting with access & refresh tokens
  commands/ # the available sub-commands taskcafe exposes
    commands.go # entry point that sets up the other commands
  db/ # database code generated by sqlc
    query/ # sql query files that are converted to go code by sqlc
  frontend/ # contains the generated frontend filesystem
  graph/ # graphql resolvers
   schema/ # contains the graphql schema declarations (which gets converted into a single schema file called schema.graphls by mage
   schema.resolver.go # contains the actual logic for all resolvers
   graph.go # contains the hasRole directory logic
  logger/ # contains custom loggers
  migrations/ # contains the generated migrations filesystem
  route/ # contains the routes for the API
   auth.go # contains the auth related routes (login, refresh, etc)
   avatar.go # contains the frontend serving code & user avatar routes
   middleware.go # contains the authentication middleware
   route.go # builds all of the routes
migrations/ # a directory of database schema migrations

GraphQL schemas

The schema for the API lives as multiple files in the internal/graph/schema/ folder.

The are converted into a single file (because gqlgen wants that) by a mage target backend:genSchema

All primary models live in _models.gql

The root Query and Mutation objects live in _root.gql

The rest of the files contain domain specific declarations. For instance the Mutations for interacting with tasks is in the task.gql file.

Database Access

Taskcafe uses sqlc (with sqlx for things that sqlc can not handle which hasn't been much so far) to handle database interactions.

internal/db exports a New method that takes in a sqlx.DB connection and returns a Repository.

The Repository contains all the methods generated by sqlc from the internal/db/query SQL files.

If you have the below query in one of the SQL files:

-- name: GetProjects :many
SELECT * FROM project;

Then the method can be accessed from the Repository like so:

projects, err := repository.GetProjects(ctx)

For more info on the sqlc query file format, take at look at its documentation.

Running in development mode

To run Taskcafe in development mode, you will need a postgres database running on your local computer (Docker is a good option for this).

Then configure Taskcafe to connect to the development database using a conf/taskcafe.toml config file (an example can be found in conf/taskcafe.example.toml).

Next open up a terminal and run the API (as well as running initial schema migrations):

go run cmd/taskcafe/main.go web --migrate

Next, start the React frontend:

cd frontend
yarn start

Now you can access the interface through http://localhost:3000 while the API is served through http://localhost:3333. The React frontend proxies all API requests to the http://localhost:3333 address.

You can find a interactive GraphQL playground at http://localhost:3333/__graphql.

Seeding the database

You can use the taskcafe seed command to generate large amounts of random teams, projects, task groups, and tasks for testing.