Skip to content

Project Structure

Jump to bottom
Jasmine Francois edited this page Jul 9, 2021 · 8 revisions

This document reflects the structure of the project in June 2021. This information may not be accurate if you are viewing this at a later date.

Rode UI was built using Next.js so some of the project structure is dictated by the framework. Those directories that are special for Next.js will be noted.

The project structure is heavily influenced by how the UI presents the ideas of "Resources" and "Policies" and how you might interact with those entities. You will see references to "occurrences", which are metadata about a resource. Think of a Docker image being built by a CI pipeline; this produces a Build Occurrence that you could see details of by viewing that resource. You will see references to the "playground", where you select a resource and a policy to see how the resource fares against the policy code.

Testing Directories

  • /__mocks__
    This directory houses manual mock implementations for tests. The directory name and location is dictated by Jest.

  • /test
    This directory houses all of the unit tests for this project. The internal structure of the directory reflects the structure of the project itself.

    • test/testing-utils houses additional tooling, such as components used to test hooks, mock object creation functions, and a render wrapper.

  • /cypress
    Holds everything related to integration tests. Integration tests are implemented using Cypress and Cucumber. The internal structure of this directory is heavily dictated by Cypress, so feel free to explore their documentation for more info.

    • /cypress/fixtures Mock data to return from API calls. The data in this directory at the time of writing this documentation was the data returned to the client from the Next.js backend, not the raw data that you would have received by calling directly to Rode.
    • /cypress/integration houses the step definition and feature files that make up the core of the integration tests. Shared step definitions live inside cypress/integration/common, and any feature-specific steps live inside of their respective directory.
    • /cypress/page-objects Tells the step definitions how to target a specific element on the page. Structured to reflect the feature files.
    • /cypress/support/commands.js A file to create custom Cypress commands. Great for any logic that you find yourself duplicating across step definitions.

UI elements and styles

  • /pages is a Nex.js special directory. Any JS file created under this directory will automatically create a route within the application. For example: creating the file pages/hello.js will allow you to navigate to localhost:3000/hello.

    • There are some special files, such as _app.js and _error.js that allow us to customize out-of-the-box Next.js features to fit our liking. Read the Advanced Features guide to learn more about those files.
    • /pages/api is another Next.js special directory, that acts in a similar way to its parent, /pages, but will create endpoints that can be reached from the client. These are structured in a RESTful way that closely resembles the Rode API.
    • /pages/api/utils holds API specific utility functions, like model mapping functions and fetch helpers.

  • /components houses all of the React components that are used in the application, with the exception of the larger page components.

    • Anything living at the root of the /components directory is a "dumb" component that can be used anywhere as long as you pass the correct props.
    • /components/icons houses all the Icons we are using in the app.
    • All the other subdirectories of /components should reflect where the actual component is used. There is a /components/shared directory that houses some things that are shared between different entities, such as the SearchBar.

  • /prism holds the code that performs syntax highlighting.

  • /styles holds all the styling for the application.

    • /styles/constants.scss holds all the named colors in the application.
    • /styles/dropdown.scss holds styles specific to the <Dropdown/> component. You can read more about styling the dropdown here.
    • /styles/globals.scss holds styles that are applied to everything within the app. Beware that anything you put in here, especially styles targeting specific classes, can clash with the names in individual modules, so only add to this when you truly want a style to be globally applied.
    • /styles/mixins.scss provides some helper functions to enable mobile styling as well as some basic transitions that you can apply to elements that need some pizazz.
    • /styles/prism.scss holds the styling to enable code syntax highlighting. See the Prism notes for more details.
    • /styles/modules holds the targeted styles for the application. The styles are structured in a similar way to the components themselves, but if you are ever lost about where to find a style, you can follow the import in the React component. You are free to import multiple CSS modules into one React component, just be conscious of conflicting class names between the imported modules.

State Management

State management in this application is inspired heavily by Redux. State is available in any component by calling useAppState() within the component. This returns two items, state and dispatch. You can manipulate state by dispatching actions.

  • /reducers hold the logic for how state should change in response to the specified action. Also holds the action names so you can know what actions are available to you to update state.
  • /providers hold the logic for creating the hook and provider that allows you to use state from anywhere. You can learn more about context and providers in the React documentation.

Everything Else

  • /docs holds all the resources used in the README.
  • /hooks stores all custom hooks.
  • /schemas stores all the form schemas used in form validation. This project uses Yup for validation.
  • /utils holds additional logic and utility functions used in the app.
    • /utils/resource-utils.js holds all the logic used to determine a resource's type, version, name, as well as other pieces of information that we want to display to the user.

Clone this wiki locally