cronicl

cronicl, verb., Welsh translation of chronicle; to create a detailed record of events over time

An educational biodiversity monitoring app for engaging young people in citizen science, created by a team at Swansea University in partnership with Down to Earth.

cronicl is not yet released, so there is no guarantee of stability or future support. This repo is for development purposes only.

Technology

• Hosted with AWS Amplify Hosting
  • Live demo is available at cronicl.matthall.io
  • CI/CD is setup to update the demo with every commit to this repo
  • AWS region is eu-west-2 (London)
• Database storage is hosted with AWS
  • Using DynamoDB for most data
  • Using S3 for media
• Backend is built with Next.js
  • Using the 'pages' router (not the app router)
• Frontend is built with React
  • Following Material Design 3 principles
  • Using the Inter typeface family
• Mapping functionality is built with maplibre
  • Using OpenStreetMap data
  • Using OpenMapTiles styles
  • Hosted with Stadia Maps

App structure

There are three main areas of the app:

1. The landing is the static, public-facing part of the app. It contains information about cronicl and links the user to the other parts of the app.
2. The dashboard is the main part of cronicl, with various menus able to provide different functionality.
   • Teachers use the dashboard to manage people, sites, captures, sessions, and more. This is how they manage the app.
   • Students use the dashboard to keep track of and explore what they've found and where.
3. The game is where Kahoot-like, interactive live sessions take place.
   • Games are setup by teachers in the dashboard
   • Students join games either by:
     • accepting an invite request through their dashboard (if they have an account)
     • entering a special join code that the teacher can show to students (if they don't have an account)

Setup

Before you start setting up this repo, consider whether you need to do with the app. Basically anything outside of the frontend UI development should probably be handled by Matt.

• Remember that if you just want to test out the latest version of this app, you can go to cronicl.matthall.io.
• Remember we have the stripped-down test repo for you to develop in without worrying about breaking this one.
• If you are doing frontend development, please make sure you sketch (at least on paper; preferably on Figma) what you're trying to do first.

Here's what you'll need to get started with developing cronicl.

Prerequisites

1. Download and install vscode
2. Install the ESLint and Prettier extensions for vscode
3. Download and install nvm.
   • Use nvm on Linux/MacOS
   • Use nvm-windows on Windows
   • Run nvm version at the command line to check it installed correctly
4. Install Node.js v18 by running nvm install 18. Node.js comes with its own package manager, npm.
   • Run node -v and npm -v to check Node and npm installed correctly
5. Ask Matt to give you:
   • Editor access to this repo, so you can make changes
   • The secret keys you need to connect to the backend services

Cloning the repo

1. Clone this repo and open the directory as a folder in vscode
2. Run npm install to download the required dependencies
3. Create a file called .env.local in the root of the project to store the secret keys Matt gave you. It should look like this (fill in the blanks):

   DTE_TEST_AWS_ACCESS_KEY_ID=<the AWS access key id>
   DTE_TEST_AWS_SECRET_ACCESS_KEY=<the AWS secret access key>
   DTE_TEST_SESSION_SECRET=<the session cookie encryption password>

4. You should be ready to go. Try running npm run dev in the vscode terminal to launch the local dev server.
   • Ctrl+' opens the vscode terminal
   • Ctrl+C will terminate the dev server when you're finished

Development

There are various commands that you'll need to work on the app, defined in the package.json file. Here's what they do:

• npm run dev starts a local dev server at localhost:8080 which hot-reloads when you make changes
• npm run build builds the app (to the ./build directory) ready for production
• npm run start will host the built version of the app locally on your computer, so you can test that the build worked
• npm run lint runs the linter, which checks that code styling is correct

Code convention

• Every time you save the file in vscode, the linter will run and keep your code conformant to the code convention for the app. Things might move around slightly when this happens.
• Importing dependencies/libraries should use the import keyword, as opposed to the old using keyword.

  // A nice, modern `import` statement
  import Link from "next/link";
  
  // Try to avoid old-style `using` statements
  const fs = using("fs");

• All frontend files containing React code should be saved as .jsx files. Any JS file without React components (mainly just backend and API routes) should be saved as .js.
• We aren't using TypeScript, but try to maintain basic JSDoc code commenting wherever possible. Example from /src/lib/auth/token.js:

  /**
   * Generate a 128-bit UUID as a token.
   * @private
   * @returns {string} A valid UUID token string
   */
  function generateToken() {
    return uuidv4();
  }

• We are using modular Sass, as opposed to plain CSS. All style code should be in a separate .module.scss file. The code is similar though, so just look at where else it's used in the repo for an idea (e.g. in /src/components/common).
• Import other files using the module path alias '@' to keep import statements clean. The '@' symbol literally just means 'start at ./src'. See:

  // Without the alias
  import Button from "../../../components/common/Button";
  
  // With the alias
  import Button from "@/components/common/Button";

• With React, prefer functional components over class components wherever possible. Class components are the old-fashioned way to do React components and they're worse in every way.

Testing

Before you push changes to this repo, make sure it all still works! You should test your changes:

• locally on the dev build (using npm run dev)
• locally on the production build (using npm run build then npm run start)

Tips

• If you're looking at the Next.js documentation, make sure you select the 'pages' router docs rather than the 'app' router ones.
• Be acutely aware of potential future costs of using paid-for libraries and tools, and consider open source alternatives where possible.
• When designing the frontend, use the Material Design 3 (M3) docs as a trusted guide. It saves a lot of thinking when it comes to responsive layouts, consistency, colour theory, and iconography.
  • Using ready-made M3 components for cronicl:

    // ExampleComponent.jsx
    import Button from "@/components/common/Button";
    
    ...
    
    // Place a button somewhere in a component
    <Button
      label="Enter"
      variant="filled"
      type="submit"
      disabled={isSubmitting}
    />

  • Using the cronicl M3 design tokens for colours and sizes:

    // ExampleComponent.module.scss
    @use "@/styles/theme";
    
    // Using various colour and size tokens
    .container-filled {
      background-color: theme.$primary;
      color: theme.$on-primary;
      border-radius: theme.$corner-large;
      margin: theme.$compact-margin;
    }

  • Using the cronicl M3 design tokens for typography and elevation:

    // ExampleComponent.module.scss
    @use "@/styles/m3";
    
    // Using a typography token
    .label {
      @include m3.body-small;
      display: flex;
      align-items: center;
    }
    
    // Using an elevation token
    .container-elevated {
      background: theme.$surface-container-low;
    }

  • Using material symbols for iconography:

    // ExampleComponent.module.scss
    @use "@/styles/theme";
    @import "material-symbols"; // this import is all you need for material symbols to work
    
    // We'll use a wrapper element for more control of styling the symbol
    // (you don't need a wrapper element, but it's recommended)
    .symbol {
      display: flex;
      justify-content: center;
      align-items: center;
      font-size: theme.$medium-symbol;
    }

    // ExampleComponent.jsx
    import style from "./ExampleComponent.module.scss";
    
    ...
    
    // Inserting a material symbol (the <span> element) into our wrapper element (the <div> element).
    // Replace "NAME OF THE GLYPH" with a real icon name from https://fonts.google.com/icons, like "cake".
    <div className={style.symbol}>
      <span className={style["material-symbols-outlined"]}>{"NAME OF THE GLYPH"}</span>
    </div>

Repo structure

Here's where the key folders you'll need are in this repo:

• /src — all the actual code for the app
  • /src/components — the parts of the UI used to build the app
    • /src/components/common — reusable M3 components
  • /src/pages — every file and folder in this directory maps directly to an app URL. For example, the code for the /login page can be found at /src/pages/login.jsx.
    • /src/pages/api — API routes
    • /src/pages/dashboard — dashboard routes
    • /src/pages/play — game routes
  • /src/styles — global styles that can be used anywhere in the app