Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 21 Next »

Frontend:

Libraries:

  • React – JavaScript library for making complex UI in a performant and maintainable way

  • Material UI – a collection of pretty pre-made UI components, designed according to well-researched UI standards

  • Cypress – an end-to-end testing library

    • Running Cypress tests will involve literally spinning up a browser and executing automated actions like clicking on buttons and asserting results after those actions

  • Jest – a unit testing library

    • When used with React Testing Library, it lets you check whether React components will have the HTML or state that you expect when an event takes place. Eg. after you perform user actions like button clicks, you might assert that a counter value goes up.

  • Various other libs – npm has a huge amount of great libraries. We’re using a number of them such as react-console-emulator, react-helmet, react-cookie, etc.

    • It’s preferable to not re-invent the wheel, but we should be careful not to bloat our package.json with poorly-supported dependencies.

Directory Structure:

Below is a breakdown of the client directory structure. This should be used as a reference for figuring out which part of the codebase is responsible for doing or displaying what.

  • For people working on the UI and design, you mainly need to be aware of what’s inside client/components and client/views.

    • For people working on the visualiser UI specifically (the controller, terminal, etc.

  • For people working on the visualiser, you mainly need to be aware of what’s inside visualiser-src.

  • For anyone trying to add a new visualiser and its commands into our webpage, see the section 'Adding a New Visualiser'.

You shouldn’t worry about any file you see in the project that isn’t included in the client directory, eg. Dockerfiles, Jest config, build folders, etc. 

client/
    package.json
    src/
        App.scss                # Contains styles that we want globally applied, eg. scrollbar styles, default fonts, etc.
        App.tsx                 # The root React UI component. This is where you should add new routes.
        assets/                 # A bunch of images, fonts and other static content that you wouldn't put next to your source code
        components/             # All our React components (minus the pages themselves - those belong in the 'views' directory!)
            Autocomplete            # Basically a dropdown that suggests autocompletion results. See mui.com/components/autocomplete/.
            Carousel                # A slide-like UI that showcases a bunch of cards that you can swipe through. See react-slick.neostack.com/.
            Code                    # Code snippets.
            ContentManagement       # A bunch of forms for creating/managing content. This is a bit of a hellhole, beware.
            Features                # Some components used to help showcase our project features on the landing page.
            Footer                  # Footer element at the bottom of some pages, showing social links and links to other places.
            Frame                   # Literally like picture 'frames', used to decorate showcase images 
            Gallery                 # A pretty container for pictures. Used to showcase a collection of items that have pictures. See mui.com/components/image-list/.
            HorizontalRule          # Basically prettier <hr /> components. See mui.com/components/dividers/.
            Lesson                  # Renders markdown lessons for a given topic. Eg. Given "Linked Lists", it talks to our API to fetch the linked list lessons we have in the database. 
            Loader                  # Some fancy spinners, used to show some content is loading. See mui.com/components/progress/.
            MarkdownEditor          # A markdown editor and renderer. See npmjs.com/package/rich-markdown-editor.
            Modal                   # Popups components - useful for showing registration forms, user confirmation popups, etc.
            Navbars                 # Top navbar and side navbar
            Panes                   # The collapsible and resizable panes used in the visualiser pages. See npmjs.com/package/react-collapse-pane.
            Particles               # The fancy floating particles you see on the landing page. See github.com/matteobruni/tsparticles.
            Quiz                    # The quiz components used by lessons. Has variants like multiple choice quiz, true/false quiz, etc.
            SplashScreen            # That in-your-face splash screen you see when you visit the landing page.
            Tabs                    # Just like Chrome tabs. It's used to organise our educational content (eg. lessons, code, videos, etc.). See mui.com/components/tabs/.
            Tags                    # A list of 'chip' components. It's mainly used to show tags for a topic like "COMP2521", "COMP1511", etc. See mui.com/components/chips/. 
            Video                   # An embedded video player for playing youtube videos, for example.
            Visualiser              # Our visualiser UI. This includes the controller UI, terminal, GUI form, etc. 
                                    # This DOES NOT include any visualiser implementation! This is purely the surrounding UI. For the actual implementation, see 'visualiser-src'
        constants/              # Contains global config and values that would otherwise be hard-coded in our source code.   
            api.ts              # This contains important API connection info, eg. what the API URL is.
            cookies.ts          # This contains the names of cookies we're using. Eg. We need a name for the cookie that tracks whether the user should have dark mode on or off.
        index.tsx               # The REAL root UI component. This should rarely be touched unless we're doing fundamental changes. See 'App.tsx'.
        layout/                              # Contains some fundamental UI that is reused by our pages. Eg. the topnav, some container padding, etc. 
            HomepageLayout.tsx               
            VisualiserDashboardLayout.tsx
        structsThemes.ts        # Our colour palette! It sets dark mode and light mode colours separately.
        utils/                  # A bunch of reusable functions.
            apiRequests.ts          # Contains all the functions you need to grab or change content from the API. Eg. there's functions for fetching lessons, topics, etc.
            markdown-util.ts        # Some functions for working with markdown.
            Notification.ts         # Spawns a small notification/popup. Great for non-invasive error messages and communicating short messages with the user.
            url.ts                  # Some string manipulation functions, specifically for working with URL-like strings.
        views/                  # Our pages. These are React components that specifically define page layout and content. For specific UI elements, see 'components'.            
            AboutUs.tsx                      
            ContentManagementDashboard.tsx   
            Feedback.tsx                     
            HomePage.tsx                     # Our landing page.
            Page404.tsx                      # A cool 404 page for when the user navigates to a route that we haven't defined. Eg. structs.sh/non-existent-page.
            VisualiserDashboard.tsx
        visualiser-src/                      # Our visualiser source code. All the internal visualiser magic happens here. This does NOT define anything related to UI - for that, see 'components/Visualiser'. 
            binary-search-tree-visualiser/   # BST visualiser layout and operations. Includes things like insertion, rotation, etc. and drawing the tree.  
            controller                       # Executes controller operations like play, pause, speed change, etc. and manages state such as the animation timeline and operations history.
            linked-list-visualiser           # Linked list visualiser layout and operations. Includes things like insertion, deletion, etc. and drawing the linked list. 
            typedefs.ts                      # Custom data types used by the Visualiser implementation.

This was last updated on 16th January, 2022.

Styling with SCSS Modules:

Using global CSS/SCSS is a nightmare in a large project because you will likely encounter name collisions and CSS specificity issues. With SCSS modules, every classname you define is 'mangled' so that it is always unique and is guaranteed to never
conflict with any other classname in the project.

How this works:

  1. Suppose you're working on LinkedList.jsx. Add a new file called LinkedList.module.scss

  2. Write your SCSS code in that file. Remember SCSS is a superset of CSS so you can just write regular CSS.

    .container {
    margin: 10px;
}

  3. Import the scss module in LinkedList.jsx and apply the style like this:

    import styles from './LinkedList.module.scss';

const LinkedList = () => {
    return <div className={styles.container}>...</div>;
};

React Visualiser UI:

This section provides an overview of the visualiser UI components hierarchy. This is probably the most complex part of the React codebase and deserves its own clarification section.

The visualiser logic and source code exists separately to the React codebase. See the ‘Visualiser Docs’ section if you are trying to learn about the visualiser implementation itself.

Visualiser Docs:

This section provides a high-level explanation of the architecture behind the visualiser’s internal logic.

Diagram:

This diagram below was built with LucidChart. It shows a bird’s-eye view of the classes and files used to build the visualiser and controller.

Adding a New Visualiser:

To add a new visualiser, you’ll need to need to make a new directory under visualiser-src and create files that follow a similar architecture as above. Use the existing linked-list-visualiser and binary-search-tree-visualiser as references.

Note that you won’t need to create the AnimationController and AnimationProducer classes – they already exist.

To make it show up on the React client, you must

  1. Add an entry for the visualiser into the ‘Topics’ section of the database

  2. Add an entry for the visualiser in the DataStructure enum type under visualiser-src/common/typedefs.ts (make sure the name is consistent with the lowercase version of the database topic title)

  3. Add a case statement for your data structure under visualiser-src/common/GraphicalDataStructureFactory.ts to return your GraphicalDataStructure.

Adding a New Operation to a Visualiser:

Creating the logic of the animations

  1. Code up the operation in the corresponding Graphical[DataStructure] in a new method. Add documentation for the arguments it accepts.

    1. Note: for now, arguments are non-negative integers between 0 and 999 only.

  2. Write up a code snippet in a separate file (in C, as a multi-line string). This should look similar to what you wrote in step 1.

  3. Identify the lines you want to animate and design the look of the animation

    1. This is up to you (be as creative as you want!), but make sure it’s consistent with the rest of the visualiser, and make sure it is true to the steps of the operation.

  4. Add a [DataStructureOperation]AnimationProducer class file under the animation-producer directory in the corresponding data structure directory in visualiser-src

  5. Code up the SVG animations for each line you want to animate – one method corresponding to each code snippet line you identified in step 3.

    1. Write a method that renders a code snippets you wrote in step 2. Make use of the renderCode(code: string) method.

    2. This involves calling addSequenceAnimation for animations that happen at the same time.

    3. TIP: Name AnimationProducer methods after the semantics of each line as opposed to its visuals. For example, .appendNode() as opposed to .showSVGAtLastPosition(). This will guide you on what the animation looks like, and decrease your chances of creating animations that are misleading.

    4. TIP: Before writing an AnimationProducer method, have a look to see whether other operations already have it.

  6. Instantiate the [DataStructureOperation]AnimationProducer class in the method you wrote in step 1 and render the code snippets.

  7. Call doAnimation (in the case that there is no corresponding code snippet line) or doAnimationAndHighlight (to highlight a code snippet line for the duration of your animation) on the AnimationProducer method and its arguments.

  8. Return the AnimationProducer from the method.

If unsure, check out the linked list and binary search tree visualiser as reference.

Backend:

For the first few months of 2022, don’t worry about this section too much. Our content API is generally lower priority in our year’s plans Vision for 2022.

Structs.sh features a RESTful API for content management, supporting the retrieval, creation, updating and deletion of lessons and quizzes as well as the management of users.

Endpoint Documentation

Our endpoint documentation is not on Confluence. To see it, start up the backend server (eg. on port 8080), then navigate to http://localhost:8080/.

What you will see is a webpage generated by Swagger that looks like this:

This lets you both see the endpoints available and actually try them out for yourself within that same page!

Tech Stack:

The backend project is set up in a way that aims to be similar to the COMP1531 main project, however it uses quite a different tech stack:

  • Node.js – for your purposes, you can think of this as just JavaScript.

    • The main difference between Node.js and client-side JavaScript is that you won’t have access to browser-specific objects like window and many web APIs.

  • Express – the most popular Node.js server framework. We’re using this library because it simplifies how we write our content management API.

    • Express is very similar to Flask. You can think of it as Node.js’ version of Flask.

  • MongoDB – the most popular NoSQL database system.

    • We chose this because of ease of use and flexibility.

    • We’re currently using an instance of MongoDB that’s hosted in the cloud. The specific platform we’re using is MongoDB Atlas, which has a generous free tier.

    • Mongoose – an object document mapper (ODM), or otherwise called an object relational mapper (ORM), for MongoDB.

      • We’re using this because it gives us a developer-friendly interface into reading/writing to our MongoDB database. This makes it so you won’t need any experience with MongoDB to be able to work with it.

        • This extra ORM layer is a fairly common even in enterprise backend systems.

  • Jest – a JavaScript testing framework for writing unit tests.

    • You can think of Jest as Node.js/JavaScript’s version of PyTest for Python.

As of 18th Jan, 2022, we don’t have unit tests or integration tests properly set up. Tim Zhang (Unlicensed) should set this up.

Pre-Requisites For Development:

Note: Although you don’t need to know about MongoDB, it’s very helpful to know a few things if you’re going to be developing the backend:

  • Basic terms used in NoSQL database: collections, documents.

  • How to access our database instance on MongoDB Atlas and browse through our collections. Tim Zhang (Unlicensed) needs to write this section.

  • (Not too important) Basic understanding of SQL and relational DBMS knowledge – mainly to help you better see the similarities and differences between relational and non-relational DBMSs.

  • We try to stick closely to REST API conventions. You should aim to develop endpoints similar to this format:

COMP1531 would have given you a good enough foundation to be able to begin with contributing to the backend.

About Swagger:

The documentation for the Structs.sh API was set up with swagger-jsdoc (https://www.npmjs.com/package/swagger-jsdoc ) and swagger-ui-express (https://www.npmjs.com/package/swagger-ui-express )

Note: swagger-jsdoc generates an OpenAPI spec from the JSDoc documentation written for each endpoint.
The package swagger-ui-express serves the documentation which can be accessed by a route you define (eg. /api-docs). It takes in the output of swagger-jsdoc to achieve this.

Developer Note: follow the YAML structure here for documenting endpoints in a way that can be used by Swagger.

Directory Structure:

Below is a breakdown of the server directory structure. 

server/
    src/
       database-helpers/     # Contains a bunch of classes that supply methods for interacting with their respective MongoDB collection.
          lesson.ts              # Gives you methods like: `createLesson`, `getAllLesson`, etc. When called, these will directly interact with and affect our database.
          quiz.ts
          source-code.ts
          topic.ts
          user.ts
       routes/               # Contains all the HTTP endpoint definitions and handlers.
          auth.ts                # Auth endpoints like `POST /register`
          health.ts              # Not important. This is for testing if the server is alive.
          lesson.ts              # Lesson endpoints like `GET /api/lessons`
          quiz.ts                # Quiz endpoints like `POST /api/lessons/quiz`
          source-code.ts         # Code snippet endpoints like `POST /api/source-code`
          topic.ts
       schemas/              # All of our MongoDB schemas. These define what our collections and documents look like.
          lesson/
             lesson.ts           # Eg. this file defines what the documents in the 'lessons' collection in our database looks like
          quiz/
             quiz.ts         
          source-code/
             source-code.ts
          topic/
             topic.ts
          user/
              user.ts
          swagger-schemas.yml.ts     # Contains metadata that Swagger uses to generate our interactive documentation. These are manually written.
       server.ts                 # This is the entrypoint of the server where we configure things and start up the server.  
       typedefs/                 # A bunch of TypeScript type definitions. Having typed data is even more helpful when working in the server-side!
          lesson
             Lesson.ts
          quiz
             MultipleChoice.ts
             QuestionAnswerQuiz.ts
             Quiz.ts
             TrueFalseQuiz.ts
          source-code
             SourceCode.ts
          topic
             Topic.ts
          user
             User.ts
       utils
           index.ts
    tests/               # Our unit tests and integration tests.

Data Model:

Below is an informal entity-relationship (ER) diagram for the data models in our content management system.

Note: This diagram was created and is currently maintained with draw.io. VSCode has a great extension for an integrated draw.io client that lets you view and edit .drawio files in the editor.

  • No labels