Case Scenario

Jutta sometimes creates a slide with an interactive word cloud question using www.menti.com or www.ahaslides.com. When she presents an online workshop, she asks the audience to answer this question by giving an URL such as https://www.menti.com/4yho9tkqux. When audience answer this question, the slide will dynamically updates by highlighting majority answers. The Wordle tool we create should perform the same workflow but generating inverted Wordles that highlight the minority answers. Jutta’s requirements include:

  1. The audience doesn’t need to pay for it or go through a lengthy sign up process. I want to give them a link directly to the page where they enter their words.
  2. The results don’t need to be embeddable as long as I can share the results when I’m presenting on a Website.

Architectural Diagram

Data Structure

The wordle questions and answers are saved as .json files in the "src/_data/" directory in the GitHub repository:

  • Every wordle question is saved as an individual .json file in the file name: {uuid}-question.json
  • Answers to a wordle question is saved as an individual .json file in the file name: {uuid}-answers.json

The format of a wordle question file

{
    "workshopName": {String},
    "question": {String},
    "entries": {Number},
    "entryMaxLength": {Number},
    "createdTimestamp": {Timestamp},
    "lastModifiedTimestamp": {Timestamp}
}

The format of a wordle answers file

{
    "{uuid}": {
        "answers": {String[]},
        "createdTimestamp": {Timestamp}
    }
    ....
}

Why Using Github Branches as Data Source

Another alternative that was considered was to save questions and answers into a third party database such as Fauna. Netlify functions will interact with it through Fauna API.

The final decision goes with Github branches is because this work will also benefit the implementation of the pluralistic data infrastructure that was planned to use Github branches and pull requests for collecting community-based user submitted data.

Lessons Learnt during Development

Ned's comments below describe the original implementation plan. The diagram above shows technologies used in the final product. There are 2 parts are changed during the development and here is why:

  1. Use Github REST API to interact with branches and files in the remote Github repository rather than using Github Actions.
    1. Why: The API that triggers a Github Actions workflow only responds whether the workflow is triggered successfully or not. When a workflow is triggered successfully, it doesn't report the result of the workflow execution. For example, if the workflow is to create a remote Github branch, in the case the workflow runs but for any reason it fails, the API response doesn't tell the run failed. The API response always returns success (response code 200) as long as the workflow is triggered.
  2. The flow that polls the answers file is to have the client page calls a server endpoint which uses Github REST API to poll rather than having the client page polling the file directly from https://raw.githubusercontent.com.
    1. Why: Raw github URLs cannot be refreshed more than once every 5 minutes. The detail of the issue using raw github URLs can be found in FLUID-6626.
  • No labels

2 Comments

  1. Ned Zimmerman

    Suggested workflow based on our conversation:

    Creating a Wordle

    1. Visit /new.
    2. Authenticate with Netlify Identity, using the Netlify Identity widget.
    3. Reveal a form to create a new Wordle, which, when submitted, creates a workflow dispatch event via a Netlify Function.
    4. The triggered GitHub action:
      1. Creates a branch using a slugified version of the Wordle name.
      2. Commits the Wordle info to the newly-created branch.
    5. Eleventy builds pages for the Wordle submission form and display page based on this data. Eleventy may need to fetch all branches as part of the build, perhaps using a JavaScript Data file.

    Responding to a Wordle

    1. Visit /the-wordle-title (this is the same as the slugified branch name).
    2. Enter a response to the Wordle, which, when submitted, creates a workflow dispatch event via a Netlify Function.
    3. The triggered GitHub action:
      1. Commits the submission info to the branch associated with the Wordle using [skip-netlify] in the commit message to avoid triggering a build (note: this may not be necessary if all branches aren't being deployed)

    Viewing a Wordle

    1. Visit /the-wordle-title/wordle (this is the same as the slugified branch name).
    2. A Netlify function retrieves the latest responses from the relevant branch and they are presented to the visitor.

    One concern I have about viewing the Wordles is that if we are running a Netlify function every time the page is viewed, that could exhaust our functions usage if there's high traffic. If I think of any solutions I'll follow up in a comment.

  2. Ned Zimmerman

    Update: I have an idea! If the Wordle responses are committed to a JSON file in each branch, we could retrieve them from Git without using a Netlify Function, for example:

    https://raw.githubusercontent.com/inclusive-design/wecount.inclusivedesign.ca/dev/src/_data/resourceTags.json

    There's a JSON file that could be loaded just using front-end JS without needing authentication. In the case of the Wordle, the URL might be something like:

    https://raw.githubusercontent.com/inclusive-design/inverted-wordle/wordle-title/src/_data/responses.json

    …where wordle-title is the slugified form of the Wordle in question, e.g. the branch name. This would mean we'd only need to run a serverless function on Wordle creation or response submission.