Getting Started

Libraries in use

The frontend uses the following libraries heavily:

• React
• Redux
• React Redux
• Redux Thunk
• React Router (but mostly only in one file)

Many other libraries are used as well (it's JavaScript, what do you expect?), but typically, either they're not critical to understanding how the application works or it's very obvious what they do. In particular:

• Axios is a promise-based JavaScript HTTP client
• immutability-helper provides some syntax sugar for creating a mutated copy of an object
• React Bootstrap provides React components for Bootstrap (NB: we use the old version with Bootstrap 3)

Be aware that most dependencies are months or years out of date, so documentation for the most recent versions may not be useful.

Where to start

The entrypoint for the application is src/index.js. This file:

• sets up the Redux store, and installs the Redux Thunk and Connected React Router middlewares
• contains the root component, App, which:
  • installs Axios interceptors to catch unhandled errors and cache/deduplicate in-flight network requests
  • fetches some basic data (e.g. the ID of the currently logged-in user) that the rest of the application uses
  • uses React Router to display other components depending on the path the user has navigated to (with an ugly special case to display a nicer error if a student tries to access the portal before they have been invited to the first rotation)
• renders the App (and the Provider from React Redux) into the element with ID root (located in public/index.html)

The rest of the frontend is roughly split up into six sections:

• public/ contains files that will be included verbatim in the build
• src/actions/ contains Redux/Redux Thunk action creators that talk to the backend API
• src/components/ contains React components that aren't a stand-alone page
• src/interceptors/ contains two Axios interceptors:
  • src/interceptors/cache.js caches in-flight network requests – since each component is (by and large) responsible for fetching its own data, many network requests can sometimes be made simultaneously to the same API endpoint; this interceptor ensures that if two requests are made simultaneously, only one network request will actually go over the wire (this may be a premature optimisation!)
  • src/interceptors/errors.js shows a pop-up message whenever a network request fails, and redirects to the login page if the failure was authentication-related (though if the request included a header called _axios, this interceptor ignores it and does not show a popup)
• src/pages/ contains larger React components which will be rendered by React Router in src/index.js
• src/reducers/ contains the Redux reducer that updates the global state based on actions emitted by the functions in src/actions/

plus a few other files:

• src/config.js extracts data from environment variables into JavaScript variables (NB: these are substituted automatically at build-time)
• src/constants.js defines things like the names of roles, the programmes a project can relate to, what grades a report can have, etc.
• src/header.js should really be in src/components/, but isn't
• src/index.css is nominally the CSS for src/index.js, but is actually just a bunch of miscellaneous styles