Backend Stack Overview

Backend Stack Overview

Layers

The backend application has a number of components that can be grouped roughly into layers. These are listed here, from the HTTP side to the database side. While some leakage is inevitable (the DB models will tend to exist everywhere, for example), the goal should be to keep layers ignorant of each other's implementation details, with increasing emphasis the further apart those layers are.

• The GraqphQL schema - defines types, queries and mutations for the graphql API, and is our coordination point with the client.
• The API package tells the graphql package how to resolve requests, through a combination of wrapper models and specialized Spring components that implement a graphql resolver interface. This layer should contain the minimum possible logic to bridge between the GraphQL view of reality and the rest of the application. Good: choosing which form of patient data to display. Bad: fetching multiple different entities and stitching them together. (That’s hypothetical, haven’t seen anything actually bad yet.) Components in this layer should not interact with Repository objects, but should understand database models. Models in this layer should only be used by resolver components.
• The service package is where all the actual logic in the application should live. All of the classes on in this package should ideally be labeled as @Transactional(readOnly=true), but at least @Transactional is required. Most query and mutation resolutions should require a single service call. Internal models for the application that are neither part of the API nor the persistence layer live here.
• The DB layer contains the model and the repository package.
  • The JPA/Hibernate persistence schema is defined in the model package, with each object that has an @Entity annotation corresponding to one primary data table. Best practices and/or local conventions for how to map your database tables in JPA are worthy of an entire page, which they may even get some day.
  • The repository package defines how we fetch data from the database: it should contain only interfaces, which are wired up into implementation classes by Spring Data JPA under the hood. (It is possible we will add some weird abstract class partial implementations at some point, but we have not yet needed to.)
• The liquibase database changelog defines the underlying structure of our postgresql database. Once a changeset in this file is merged to master, it basically cannot be modified (other than adding comments and tweaking settings about when a given migration runs), so please take extreme care when adding things to this. (Also, the wrong change here could wipe our database instantly. Just FYI.)

Configuration

• config package
• profiles
• YAML files