Client

• index.ts: Some React boilerplate code that you shouldn’t need to touch. This is the root file, which imports from App.tsx, where most of the top-level code lives.

• App.tsx: The “main” file in the project, which brings in all of the big components in the app.

• service-worker.ts and serviceWorkerRegistration.ts: don’t ask

• api directory: How the front-end fetches the data it needs from the back-end, by sending network requests to our server.

  • getAutoTimetable.ts: Fetches a timetable generated by the autotimetabler.

  • getCoursesList.ts: Fetches the list of courses. This list only contains a summary of each course, to save network bandwidth.

  • getCourseInfo.ts: Fetches detailed data for a single course, once you have selected it. This data includes all the classes for the course which will show up in the timetable.

  • config.ts: The URLs for where we should send network requests.

• assets directory: Where images and other media are, including the logo.

• components directory: Contains a bunch of files which App.tsx imports, with most of the app’s components.

  • controls directory: Files related to the controls located above the timetable

    • Autotimetabler.tsx: The autotimetabler button and dropdown menu

    • Controls.tsx: The parent component for all the controls

    • CourseSelect.tsx: Where you search for and select your courses.

    • CustomEvent.tsx: Where you create a custom event or tute/tute + lab card for tutors

    • CustomEventGeneral.tsx: Component used in CustomEvent.tsx where you create a general custom event.

    • CustomEventTutoring.tsx: Component used in CustomEvent.tsx where you create a tute/tute + lab card.

    • History.tsx: The undo, redo and reset buttons

  • navbar directory: Files related to the components in the navbar located at the top of the page

    • Navbar.tsx: The navbar itself, which has the title and icons for opening the various modals.

    • CustomModal.tsx: The wrapper for the modals in the navbar.

    • About.tsx: The about modal’s content.

    • Changelog.tsx: The changelog modal’s content.

    • Privacy.tsx: The privacy modal’s content.

    • Settings.tsx: The settings modal’s content.

  • timetable directory: The timetable contains 3 main layers, which are TimetableLayout.tsx, DroppedClasses.tsx, and Dropzones.tsx.

    • Timetable.tsx: The entrypoint for the timetable, which imports all the other timetable components.

    • TimetableLayout.tsx: The 1st layer, containing the grid that backs the timetable, the hours on the left, and the days at the top. Provides the base users need to understand what’s happening in the timetable. Users can also create a general custom event by double-clicking on any timetable grid square.

    • DroppedCards.tsx. The 2nd layer, which has all the classes and events which you can drag around the timetable. It has a component which aggregates all the classes and events, and a component representing each class and event.

      • DroppedClass.tsx: A single class in the timetable. This may be a scheduled or unscheduled (inventory) class

      • DroppedEvent.tsx: A single event in the timetable.

    • Dropzones.tsx: The 3rd layer, containing all those highlighted parts on the timetable which you see while dragging. They’re targets for where you can drop a class. This file puts together all the dropzones in the timetable.

    • Dropzone.tsx (not plural): This component represents a single dropzone.

    • ExpandedClassView.tsx: The dialog that appears when you click the meatballs menu icon in a class card.

      • PeriodMetadata.tsx: Additional information about a particular class such as its capacity, whick weeks it runs, and its location

    • ExpandedEventView.tsx: The dialog that appears when you click the meatballs menu icon in a custom event card.

      • DiscardDialog.tsx: The dialog that pops up when you have unsaved changes while editing a custom event

    • DropdownOption.tsx: The horizontal options selector used for selecting a day of week for custom events or the mode of teaching in the autotimetabler

    • CreateEventPopover.tsx: Custom event popover for when user double clicks on a timetable grid square. Uses CustomEventGeneral.tsx and is used in TimetableLayout.tsx.

  • Alerts.tsx: The pop-up alerts that appear on the bottom of the page (e.g. when something goes wrong)

  • Footer.tsx: The text and links at the bottom of the page.

• constants directory: All the static configuration stuff for the app.

  • defaults.ts: A pretty important file when it comes to storing permanent data (”local storage” in the browser).

    • Local storage (and cookies) are things which remain stored even after you close the browser tab. For us, this includes your courses, timetable, and settings like wheter dark theme is toggled on.

    • This file provides default values for stored items, which are used when you visit the page for the first time.

    • When you add a new thing to local storage, you need to include it in defaults.ts for it to work, with how we’ve got it set up at the moment.

  • theme.ts: Describes some global settings such as padding and how rounded corners should be, as well as the colours in light and dark theme.

  • timetable.ts: Some timetable constants such as the colours to use for each class, default starting and ending times, and the function used to get which term/year it currently is from the scraper.

• context directory: All the context stores for the app. This is where all application state which needs to be shared between components is contained.

  • AppContext.tsx: Context store for most of the things we need to keep track of state for.

  • CourseContext.tsx: Context store for a user’s selected courses, selected classes and created events. This is separate to the other context store because these states need to be optimised using useMemo() to prevent lag when dragging classes around.

• hooks directory: Get someone to explain how React hooks work... there’s a few in here anyway.

  • useColorMapper.ts: Assigns the colours for each course in the timetable.

    useUpdateEffect.ts: A bit of a hack I think, but it’s useful when you want a hook to only run when a component updates, but not when it mounts (is created). It’s used in App.tsx. For more context, see: https://stackoverflow.com/q/55075604.

• interfaces directory: All of the app’s interfaces are here. An interface is a bit like a struct in C.

  • Course.ts: All the interfaces for courses for the CourseSelect component and the data that comes from the back-end.

  • Database.ts: Database is a bit of a misnomer now that we’re not using a database in the back-end, but this file has the interfaces which describe data that we receive from the back-end.

  • Periods.ts: All the interfaces for the cards on the screen, whether they be scheduled classes, custom events, or in the inventory.

  • PropTypes.ts: All the interfaces defining a component’s props

  • NetworkError.ts and TimeoutError.ts: Just simple subclasses of the built-in Error class, so we can tell the difference between them.

• styles directory: If multiple components share the same Styled Components, this is where they belong. The files are named based on what components share those styles.

• utils directory: Miscellaneous code which might not belong anywhere else.

  • areValidEventTimes.ts: Checks whether a provided start and end time of a custom event is valid

  • clashes.ts: Generates a data structure to determine which classes/events are clashing with each other

  • convertTo24Hour.ts: Converts a given time to 24-hour format

  • Drag.ts: Where most of the drag-and-drop stuff happens. We implemented DnD from scratch, because we need a pretty custom solution. And it works at a level below React (in the DOM), to make the experience smoother and more responsive. It has to interact with our React code in some interesting ways.

  • generateICS.ts: Logic required to generate an ICS file to import into your calendar app from the user’s selected classes.

  • storage.ts: There’s a bit more explanation above with defaults.ts, but basically this file is how we store data in the browser permanently, such as your settings, courses, and timetable.

  • timeoutPromise.ts: A nice promisified timer function. A “promisified” function is one that is converted from using callbacks, to promises. You can ask someone what a promise is (in short, they’re nicer than callbacks).

  • translateCard.ts: Every card on the screen spawns in the top left corner, Monday 9 am. The functions in this file returns the necessary CSS to translate each card and its dropzone vertically and horizontally to its correct position on the timetable. It takes into account:

    • What day the card is on

    • How many days are currently displayed in the timetable (e.g. 5 by default, but more if the user has a weekend class/event)

    • What time the card starts and ends

    • How the card is positioned relative to other cards in its clash group (i.e. other cards it is clashing with)

Server (TODO)

• app.ts: Where all the server middleware and routes are declared

• config.ts: The URLs for where we should send network requests

• index.ts: The index route (/) where we send a simple ‘Hello World’ message to the user

• controllers folder: All the controllers (i.e. handler functions) for the various functions of the backend

  • getAutotimetable.ts: Parses the constraints passed in from the frontend and fetches a possible timetable based on those constraints.

  • index.ts: Contains all the controller functions so that they can all be imported from the one place.

• proto folder: All the generated classes and interfaces from the .proto file (which is found in /auto_server

Autotimetabling Server

• auto.py: Where the constraint programming algorithm lives

• autotimetabler_pb2_grpc.py and autotimetabler_pb2.py: All the generated classes from the .proto file

• autotimetabler.proto: Where we specify the types of RPC messages being passed between the main Notangles server and the autotimetabling server.

• requirements.txt: The required packages for the server to run. Used when installing with pip

• server.py: Where the gRPC server lives

Other files

These files probably won’t be worked on by you but it’s good to know what they do. They may appear in multiple directories (e.g. package.json) but each one is different!

• package.json: The necessary packages required for the project and the aliases for the npm start, npm build commands etc. This is where npm run start:mock comes from.

• package-lock.json: The exact steps taken by npm to install all the packages and their dependencies. Important in the deployment process.

• .gitignore: The files and folders not to be committed to Git, such as node_modules

• .prettierrc: The configuration for the Prettier extension

• tsconfig.json: The rules defining how to transpile the Typescript code into Javascript during the build process.

• Dockerfile: The instructions on how to create a Docker image from the code in the folder.

• dockerignore: The files not to include in the Docker image.

• renovate.json: The rules for our automatic package updater