Skip to content

Tymly 2.0 design session

Jump to bottom
Meena Hoda edited this page Nov 28, 2018 · 6 revisions

Tymly 2.0 Design Session

Introduction

We had a Design Session 27/11/18 about how to turn our current Tymly Application MVP into a more fully-fledged production app, given the very many stories we currently have in our framework backlog.

Participants:

Entities

We discussed several high-level entities that are in-play in both the front and back ends:

1. Documents

A "doc" (document) is to be considered a unit of related data. Just like a document in a noSQL database such as MongoDB:

Examples of a document:

  • An incident
  • A fire Safety inspection
  • A gazetteer property
  • A gazetteer street
  • A water hydrant

...and of course many, many more. To complement a JSON structure that defines a particular unit of information, we discussed some additional attributes:

Doc Attribute Description
uuid A universally unique identifier associated with the document.
data The raw data of the document.
shasum A sha1sum value calculated from the value of data that can be used for speedy comparisons and integrity checking of the document.
created The timestamp of when the document was first created.
shasumModified When the shasum value (and therefore the value of data) last changed. Will be equal to created on its first appearance.
  • If we want to think in terms of Model/View/Controller (if anyone does that anymore?) then "docs" are firmly in the model camp.

2. Cards

At this stage we see a card as a thing that adds many more explicitly named attributes to a doc.

  • One doc can result in zero-or-more cards.

Some examples of additional card attributes, not exhaustive:

Card Attribute Description
uuid A universally unique identifier associated with the card.
docId The doc from which this card has been pressed.
title Something you might expect to see in a search result. Used for human-recognisable identification purposes.
subTitle Same as title but slightly more specific.
description A short-and-snappy description of the important bits of info the card is representing.
lat long Coordinates if the card can be placed on a map somewhere.
eventDate If the card is predominantly associated with a certain date/time then this is that.
search A string that should be indexed with normal prioirty (we can also have explicit searchHigh and searchLow strings to help assist ranking algorithms.
audience An array of roles which can access this card (probably be more explicit with finer-grained permissions: read/change doc/delete doc etc.)
marking Identifies the protective marking/handling rules associated with the data.
parentId To get a parent-child relationship going with cards.
  • And it goes on... 😀

But in principle: one doc can yield many cards, with different access levels/content etc.

3. Presses

A press is the term we're giving to the process of taking the raw "data pulp" of a document and pressing it into a card.

  • Each press is responsible for pressing one type of card.
  • So a document is pressed into a card by zero or more presses.

The mechanics of how presses are to work is not for now. We did discuss the use of Apache Kafka and similar. Just getting the term down for now!

4. Templates

Users will need to be able to:

  • Provide data (documents) to a press
  • Read card/doc data in a slightly more approrate way than dealing in JSON documents.

To achieve this we have "templates". Because we've got this whole printing-press vibe going on.

  • A template is a chunk of JSON that's used to render a UI declarativly.
  • We're building on our Cardscript project to adopt the Adaptive Card spec.
  • Except for a small part in a video about Adaptive Cards 2.0 ideas, Adaptive cards doesn't explicitly define a templating syntax. So... ${cardTitle} or something? See data: {} there?
  • We also need to extend the template idea to support default values.

In summary... docs/cards plus templates equals a UIs.

Tymly GraphQL API

We talked about how all these entities will glue together. Based on our experience with the MVP, and the prototypes, we threw down some early principles:

  • We want to start building the app to interact with a GraphQL API.
  • We had good success with Apollo server, so we'll continue with that.
  • The various queries/mutations supported by our API should be arranged into the following schemas:
    • docs
      • Predominantly a addDoc mutation for adding/modifying doc content. The various presses will then look at the data payload and press them into cards as necessary.
    • cards
      • Various query-related things like getCard, getCards, getCardsNearby etc.
    • admin
      • Bit sketchy, but health-check, dashboard endpoints... pretty much "anything else".

Implementation approach

We talked about how to get things moving in the short-term. We don't have the luxuary of wholesale v2.0 development (i.e. both frontend and backend overhauls) at the moment, given our backlog.

  • We decided to develop tymly-graphql-plugin which will work like our current REST plugin, but expose the schemas as described above.
  • It is then the responsibility of the plugin to enact the necessary state machines (e.g. search, remit etc.) to honour the contract the client is being built to expect.
  • In time, our roadmap could be refactored to include a more separated "card service" architecture... if this thing flies.

Tymly Frontend

And so the requirements of the Tymly App frontend distils down to the following (most of which have been proven in the various prototypes, so confidence is pretty high).

  • A Quasar PWA app.
  • With Auth0 "embedded" login/logout routes (i.e. no Auth0 Lock).
  • To adhere to the GDS Design System as much as possible.
  • Cardscript to reconcile Adaptive Cards, Quasar and GDS components/elements.
  • Good success with Apollo Client, so still use that.

Frontend architecture approach

We're looking to use IndexedDB on the client.

  • The app will interact with the GrapHQL API.
  • And, at a high level, maintain locally a set of templates that the user is entitled to create docs with, or view docs/cards with (more thinking required here... is it just docs? Or either doc/card? both?).
  • The user then can create docs for templates marked as "this template allows the user to create a new doc from scratch".
  • The app also allows users to search cards, and view the related doc via a template (which will be locally available).
  • Docs the user has changed/created will be help locally... and marked to be sent to GraphQL as a mutation. This is in essence an Outbox if no connectivity.
  • Similarly, to-do-list docs/cards could be synchronised locally, so they're available offline.
  • Talk of Service Works to achieve this was discussed. But needs to be "functional" in IE11.
  • interesting Apollo caching/offline packages, which might help a lot, so worth investigating.
Clone this wiki locally