This document contains a high-level overview of the Lighthouse frontend's, i.e. LUNA's, architecture and code structure. Thus the document may be especially of interest to new contributors or anyone else who's curious about the implementation.
Conceptually LUNA is a single-page application that uses the component-based React and HeroUI (formely NextUI) frameworks to for its UI. Routing is managed client-side using react-router.
LUNA is packaged as a Create React App application that uses Craco to customize the Webpack configuration. ESLint and Prettier are used as linters to enforce a consistent code style.
Finally, LUNA is deployed using a containerized Nginx instance that effectively just serves up the Webpack-bundled/built LUNA as a static page.
The top-level App.tsx hosts the root component for the app. This mainly wraps a number of context providers for all state that is managed globally (e.g. the color scheme, auth/model server clients, persisted UI state like user pins etc.). Peeling away these wrappers, we get the "actual" root component, namely <RouterProvider>. This presents a view based on the path in the URL. These views are called "screens" in our terminology and are discussed in detail below.
The basic folder structure is based on the "grouping by file type" convention and contains the following top-level folders:
| Name | Description |
|---|---|
/components |
Reusable, isolated components that usually don't depend on contexts or similar |
/constants |
Enums and other constants that are used globally |
/contexts |
Custom React contexts for global state. Examples include AuthContext and ModelContext, which manage connections to the auth API and the model server, respectively. UI state (e.g. the color scheme, user pins etc.) is also managed through a context, usually either because it is persisted to the user's local storage (e.g. user pins) or because it's global (e.g. display search). |
/hooks |
Custom React hooks, i.e. simple functions that abstract over other hooks. These are used for a wide variety of things that refer to something stateful (anything that can be expressed in terms of the built-in hooks like useState, useContext, ...). Convenient examples include useStream, which automatically creates/manages a stream to some model server resource. |
/modals |
Modal components (i.e. popups) |
/routes |
Constants declaring the route tree with its components. Add new routes here. |
/screens |
Screen components, i.e. generally non-reusable top-level views |
/utils |
Reusable utility functionality that generally doesn't depend on React |