front-end architecture

The architecture of a 'React application' should be such that the user interface (written using the React library) is a layer of superficial tissue around a robust Javascript application. This React-layer should be as thin as humanly possible. Keeping this layer thin helps us avoid testing React components. Instead, we write end-to-end tests and rely on QA to ensure that the UI is working.

Diagram of architecture

Table of Contents

• dependencies
  • query/mutate data as enabled by GraphQL APIs using network-only urql clients
  • store and cache application data (gotten via GraphQL APis) in RxDB collections
  • which expose observable queries using rxjs Observables
  • which can be subscribed to in a React component using observable-hooks
• src
  • app
  • GraphQL Operations
  • services
  • db
  • util
  • rxjs: How to develop rxjs operators
  • rxdb/operators: Operators for transforming RxDocuments to a format usable in a React context
  • screens
  • gql types
• testing
  • gql test-fixtures
• topics
  • functional core / imperative shell
  • how to write React Components
  • file organization
  • patterns and anti-patterns
  • state management

Getting Started With This App

You'll need

• a config.json pointing to some environment (I point to devl personally)
• a credentials.json containing an object {username, password} with valid credentials for that environment.

At that point, you can

yarn
yarn gen
yarn start

Testing

yarn test:unit
yarn test:integrations

To run integration tests, you will need to have a credentials file at <repo-root>/test-credentials.json. This is in the same format described above (in Getting Started). You can also use a <repo-root>/test-config.json file. In the absense of either of these, the test suite fallsback to <repo-root>/{credentials,config}.json.

For more info on how and what to test, see the testing doc.

Anticipated Challenges

• Front End DB migrations

Objectives

• ~select and create a network-only GraphQL client~
  • ~use client to query / mutate data~
• ~setup and use an RxDB instance~
  • ~in memory~
  • ~persistent~
• ~organize app as singleton instance, globally importable by app~
• ~enable configuration of environment (APIs) and credentials, for authenticated use of APIs~
• ~query and subscribe to data in RxDB and generate views from these data; use react-router to create Screens~
  • ~JobList~
  • ~Job~
  • ~Content~
• ~demonstrate organization of app components in directory structure~
• ~setup integration test bed for application code~
• ~demonstrate unit tests of RxJs operators~
• ~write an integration test for an 'imperative shell' (e.g., 'query and cache a Job')~
• ~generate RxSchema types from GraphQL schema~
• ~generate TypeScript types from GraphQL schema~
• ~generate test fixture factories from GraphQL schema~
• ~implement throttled batch-get of a given resource~
• ~document high level components, technologies, with links to resources for further reading~
• demonstrate a data migration
• authentication as not a strict gate
• demonstrate a view with multiple queries
• document anti-patterns
• generate graphql fragments
• ~add max-batch-size to batch-bufferer~
• implement knowledgebase search
• add sign-in page, demonstrate app architecture with auth/not auth delineation
• implement model-layer for persistent, offline-first mutations of resources

Miscellany link dump

• urql graphql client
• rxdb
  • JSON schema
  • rxdb-utils, hooks
  • mquery methods
• observable-hooks