-
Notifications
You must be signed in to change notification settings - Fork 26
Tymly 2.0 design session
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:
We discussed several high-level entities that are in-play in both the front and back ends:
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.
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.
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!
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? Seedata: {}
there? - We also need to extend the template idea to support default values.
In summary... docs/cards
plus templates
equals a UIs.
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.
- Predominantly a
-
cards
- Various query-related things like
getCard
,getCards
,getCardsNearby
etc.
- Various query-related things like
-
admin
- Bit sketchy, but health-check, dashboard endpoints... pretty much "anything else".
-
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.
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.
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.