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