Skip to content

Commit

Permalink
docs(frontend): code structure (#89)
Browse files Browse the repository at this point in the history
An overview of the React app structure. Renames `config/view-layers` to `config/data-layers`, to avoid conflicts with `config/view-layers.ts`. Removes the old Create React App TypeScript config.
  • Loading branch information
eatyourgreens authored Aug 9, 2024
1 parent 7a7ed5f commit 1fbf59b
Show file tree
Hide file tree
Showing 111 changed files with 142 additions and 80 deletions.
63 changes: 63 additions & 0 deletions frontend/docs/structure.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Code structure

Author: Jim O'Donnell

Date: 9 August 2024

- `src/`
- `config/` - contains the configuration and code related to the various
datasets and visualisation layers, as well as other pieces of configuration.
- `data-layers/` - config for individual data layers. There should be a folder here for each entry in `config/view-layers.ts`
- `assets/` - common functionality for "vector assets" - vector feature
layers that can have damages data visualised on them.
- `basemaps.ts` - configuration of basemap styles.
- `interaction-groups.ts` - configuration of all the interaction groups
available in the app.
- `map-view.ts` - configuration of the initial map view coordinates, zoom
etc.
- `sections.ts` - style config for the sidebar sections.
- `sources.ts` - functions to build URLs to access datasets in the
vector/raster backends.
- `view-layers.ts` - a list of the view layer IDs used by the map.
- `views.ts` - default sidebar state (visible/hidden, expanded/collapsed etc.) for the individual map views.
- `details/` - UI and logic for displaying details when a vector feature is clicked in the map.
- `lib/` - self-contained library code which should be unrelated to the specific
datasets/content of the app. **NOTE** there is an ESLint rule enforcing that
files inside the `lib` folder cannot import code from any other folder in
the project, to enforce the separation between generic and content-specific
code.
- `map/` - UI, layout and behaviour of the main map view of the app. Contains
also the code for displaying basemap selection, legend for current layers,
tooltip for current hover.
- `pages/` - contents and layouts of the main pages of the app.
- `sidebar/` - the main layer selection sidebar.
- `sections/` - UI components for the controls displayed in various sidebar
sections. Specific to the datasets displayed in the app.
- `ui/` - components shared by the sidebar contents.
- `SidebarContent.tsx` - defining the overall contents of the sidebar.
- `SidebarPanel.tsx` - each section in the sidebar should be composed from `SidebarPanel`.
- `url-state.tsx` - Recoil state synchronising the state of the sidebar
sections to the URL.
- `state/` - Recoil state for the app.
- `data-selection/` - state used by layer selection sidebar.
- `layers/` - state which creates the view layer instances based on app
state and data selection state.
- `data-layers/` - state of the layers pertaining to individual datasets. There should be one file here for each identifier in `config/view-layers.ts`.
- `ui/` - special layers for UI (e.g. feature bounding box layer.)
- `interaction-groups.ts` - state containing all active interaction groups.
- `view-layers.ts` - state combining all active view layers.
- `view-layer-params.ts` - state setting up the dynamic view layer
parameters.
- `map-view/` - map view state and syncing it to the URL.
- `data-params.ts` - view layer data parameters. Updated from the sidebar and used to construct map tile URLs.
- `sections.ts` - section state for individual sidebar sections.
- `view.ts` - view state for individual map views.
- `api-client.ts` - singleton instances of API clients.
- `App.ts` - main React app component.
- `index.css` - global styles (avoid, set styles in components instead.)
- `index.tsx` - Vite app entry point.
- `Nav.tsx` - main navigation component.
- `query-client.ts` - singleton instance of react-query client.
- `theme.ts` - MUI theme configuration.
- `use-is-mobile.ts` - util hook.
- `vite-env.d.ts` - Vite types inclusion.
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { HAZARDS_METADATA } from 'config/view-layers/hazards/metadata';
import { HAZARDS_METADATA } from 'config/data-layers/hazards/metadata';
import { FieldSpec, FormatConfig } from 'lib/data-map/view-layers';
import { isNullish, numFormat, numFormatMoney, paren } from 'lib/helpers';
import startCase from 'lodash/startCase';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
import { ViewLayer } from 'lib/data-map/view-layers';
import { COLORS } from './colors';
import { assetViewLayer } from 'config/view-layers/assets/asset-view-layer';
import { assetViewLayer } from 'config/data-layers/assets/asset-view-layer';
import { border, fillColor } from 'lib/deck/props/style';
import { assetDataAccessFunction } from 'config/view-layers/assets/data-access';
import { assetDataAccessFunction } from 'config/data-layers/assets/data-access';

enum BuildingType {
commercial = 'commercial',
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { createElement } from 'react';

import { ASSETS_SOURCE } from 'config/view-layers/assets/source';
import { ASSETS_SOURCE } from 'config/data-layers/assets/source';
import { colorMap } from 'lib/color-map';
import { ViewLayer } from 'lib/data-map/view-layers';
import { VectorTarget } from 'lib/data-map/types';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { createElement } from 'react';

import { ASSETS_SOURCE } from 'config/view-layers/assets/source';
import { ASSETS_SOURCE } from 'config/data-layers/assets/source';
import { colorMap } from 'lib/color-map';
import { ViewLayer } from 'lib/data-map/view-layers';
import { VectorTarget } from 'lib/data-map/types';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { ViewLayer, ViewLayerFunctionOptions } from 'lib/data-map/view-layers';
import { assetViewLayer } from 'config/view-layers/assets/asset-view-layer';
import { assetDataAccessFunction } from 'config/view-layers/assets/data-access';
import { assetViewLayer } from 'config/data-layers/assets/asset-view-layer';
import { assetDataAccessFunction } from 'config/data-layers/assets/data-access';

export function infrastructureViewLayer(
assetId: string,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import { infrastructureViewLayer } from './infrastructure-view-layer';
import { StyleParams, ViewLayer } from 'lib/data-map/view-layers';
import { fillColor, strokeColor } from 'lib/deck/props/style';
import { dataColorMap } from 'lib/deck/props/color-map';
import { getAssetDataAccessor } from 'config/view-layers/assets/data-access';
import { getAssetDataAccessor } from 'config/data-layers/assets/data-access';
import { colorMap } from 'lib/color-map';
import { NETWORKS_METADATA } from './metadata';
import { iconType } from 'lib/map-shapes/deck-icon';
Expand Down
12 changes: 6 additions & 6 deletions frontend/src/config/sections.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
import { StyleSelectionOption } from 'state/sections';
import { BUILDING_STYLES } from './view-layers/buildings/styles';
import { DROUGHT_STYLES } from './view-layers/droughtRisks/styles';
import { NETWORK_STYLES } from './view-layers/networks/styles';
import { REGION_STYLES } from './view-layers/regions/styles';
import { MARINE_STYLES } from './view-layers/marine/styles';
import { TERRESTRIAL_STYLES } from './view-layers/terrestrial/styles';
import { BUILDING_STYLES } from './data-layers/buildings/styles';
import { DROUGHT_STYLES } from './data-layers/droughtRisks/styles';
import { NETWORK_STYLES } from './data-layers/networks/styles';
import { REGION_STYLES } from './data-layers/regions/styles';
import { MARINE_STYLES } from './data-layers/marine/styles';
import { TERRESTRIAL_STYLES } from './data-layers/terrestrial/styles';

export const SECTIONS_CONFIG: Record<string, { styles?: Record<string, StyleSelectionOption> }> = {
assets: {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { Box } from '@mui/system';
import { ExpandableRow } from 'asset-list/ExpandableRow';
import { SortedAssetTable } from 'asset-list/SortedAssetTable';
import { ListFeature } from 'asset-list/use-sorted-features';
import { getAssetDataFormats } from 'config/view-layers/assets/data-formats';
import { getAssetDataFormats } from 'config/data-layers/assets/data-formats';
import { FeatureSidebarContent } from 'details/features/FeatureSidebarContent';
import { BoundingBox, extendBbox } from 'lib/bounding-box';
import { colorMap } from 'lib/color-map';
Expand Down
2 changes: 1 addition & 1 deletion frontend/src/details/features/FeatureSidebarContent.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import {
WaterPipelineDetails,
WaterSupplyNodeDetails,
} from './detail-components';
import { NETWORKS_METADATA } from 'config/view-layers/networks/metadata';
import { NETWORKS_METADATA } from 'config/data-layers/networks/metadata';
import { ColorBox } from 'map/tooltip/content/ColorBox';
import { ApiClient } from 'lib/api-client';
import { DamagesSection } from './damages/DamagesSection';
Expand Down
2 changes: 1 addition & 1 deletion frontend/src/details/features/damages/DamagesSection.tsx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { Download } from '@mui/icons-material';
import { FormControl, InputLabel, IconButton, MenuItem, Select, Typography } from '@mui/material';
import { Box } from '@mui/system';
import { HAZARD_DOMAINS } from 'config/view-layers/hazards/domains';
import { HAZARD_DOMAINS } from 'config/data-layers/hazards/domains';
import { ExpectedDamage, ReturnPeriodDamage } from 'lib/api-client';
import { downloadFile, titleCase, unique } from 'lib/helpers';
import { useSelect } from 'lib/hooks/use-select';
Expand Down
2 changes: 1 addition & 1 deletion frontend/src/details/regions/RegionDetailsContent.tsx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { Typography } from '@mui/material';
import { REGIONS_METADATA } from 'config/view-layers/regions/metadata';
import { REGIONS_METADATA } from 'config/data-layers/regions/metadata';
import { DataItem } from 'details/features/detail-components';
import { InteractionTarget } from 'lib/data-map/types';
import { numFormat } from 'lib/helpers';
Expand Down
4 changes: 2 additions & 2 deletions frontend/src/details/solutions/SolutionsSidebarContent.tsx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { Typography } from '@mui/material';
import { terrestrialSlope, terrestrialElevation } from 'config/view-layers/terrestrial/color-maps';
import { MARINE_HABITATS_LOOKUP } from 'config/view-layers/marine/domains';
import { terrestrialSlope, terrestrialElevation } from 'config/data-layers/terrestrial/color-maps';
import { MARINE_HABITATS_LOOKUP } from 'config/data-layers/marine/domains';
import { DataItem } from 'details/features/detail-components';
import { colorMap } from 'lib/color-map';
import startCase from 'lodash/startCase';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { Typography } from '@mui/material';
import { NETWORKS_METADATA } from 'config/view-layers/networks/metadata';
import { NETWORKS_METADATA } from 'config/data-layers/networks/metadata';
import { DataItem } from 'details/features/detail-components';
import { VectorTarget } from 'lib/data-map/types';
import { FC } from 'react';
Expand Down
2 changes: 1 addition & 1 deletion frontend/src/pages/AssetListPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { SortedAssetTable } from '../asset-list/SortedAssetTable';
import { ListFeature } from '../asset-list/use-sorted-features';
import { ExpandableRow } from 'asset-list/ExpandableRow';
import { FeatureSidebarContent } from 'details/features/FeatureSidebarContent';
import { getAssetDataFormats } from 'config/view-layers/assets/data-formats';
import { getAssetDataFormats } from 'config/data-layers/assets/data-formats';

export const AssetListPage = () => {
const [layerSpec] = useState({
Expand Down
1 change: 0 additions & 1 deletion frontend/src/react-app-env.d.ts

This file was deleted.

14 changes: 7 additions & 7 deletions frontend/src/sidebar/SidebarContent.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ import { useRecoilValue } from 'recoil';

import { viewState } from 'state/view';

import { BuildingsSection } from './buildings/BuildingsSection';
import { DroughtsSection } from './drought/DroughtsSection';
import { HazardsSection } from './hazards/HazardsSection';
import { NetworksSection } from './networks/NetworksSection';
import { RegionsSection } from './regions/RegionsSection';
import { MarineSection } from './solutions/MarineSection';
import { TerrestrialSection } from './solutions/TerrestrialSection';
import { BuildingsSection } from './sections/buildings/BuildingsSection';
import { DroughtsSection } from './sections/drought/DroughtsSection';
import { HazardsSection } from './sections/hazards/HazardsSection';
import { NetworksSection } from './sections/networks/NetworksSection';
import { RegionsSection } from './sections/regions/RegionsSection';
import { MarineSection } from './sections/solutions/MarineSection';
import { TerrestrialSection } from './sections/solutions/TerrestrialSection';
import { ErrorBoundary } from 'lib/react/ErrorBoundary';
import { MobileTabContentWatcher } from 'pages/map/layouts/mobile/tab-has-content';

Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { NETWORKS_METADATA } from 'config/view-layers/networks/metadata';
import { NETWORKS_METADATA } from 'config/data-layers/networks/metadata';
import { ParamChecklist } from 'lib/controls/params/ParamChecklist';
import { useRecoilState } from 'recoil';
import { LayerLabel } from 'sidebar/ui/LayerLabel';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { ErrorBoundary } from 'lib/react/ErrorBoundary';
import { StyleSelection } from 'sidebar/StyleSelection';
import { SidebarPanelSection } from 'sidebar/ui/SidebarPanelSection';
import { SidebarPanel } from '../SidebarPanel';
import { SidebarPanel } from 'sidebar/SidebarPanel';
import { BuildingsControl } from './BuildingsControl';

export const BuildingsSection = () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@ import { Checkbox, Divider, FormControlLabel } from '@mui/material';
import {
DroughtOptionsVariableType,
DROUGHT_OPTIONS_VARIABLE_LABELS,
} from 'config/view-layers/droughtOptions/metadata';
} from 'config/data-layers/droughtOptions/metadata';
import {
DroughtRiskVariableType,
DROUGHT_RISK_VARIABLE_LABELS,
} from 'config/view-layers/droughtRisks/metadata';
} from 'config/data-layers/droughtRisks/metadata';
import { ParamDropdown } from 'lib/controls/ParamDropdown';
import { FC } from 'react';
import { useRecoilState } from 'recoil';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { ToggleSection, ToggleSectionGroup } from 'lib/controls/accordion-toggle/ToggleSection';

import { hazardSelectionState } from '../../state/data-selection/hazards/hazard-selection';
import { hazardSelectionState } from 'state/data-selection/hazards/hazard-selection';
import { InputRow } from 'sidebar/ui/InputRow';
import { InputSection } from 'sidebar/ui/InputSection';
import { ReturnPeriodControl } from 'sidebar/ui/params/ReturnPeriodControl';
Expand All @@ -9,7 +9,7 @@ import { RCPControl } from 'sidebar/ui/params/RCPControl';
import { useRecoilValue } from 'recoil';
import { showDamagesState } from 'state/data-selection/damage-mapping/damage-map';
import { Alert, Box } from '@mui/material';
import { HAZARDS_UI_ORDER, HAZARDS_METADATA } from 'config/view-layers/hazards/metadata';
import { HAZARDS_UI_ORDER, HAZARDS_METADATA } from 'config/data-layers/hazards/metadata';

function HazardToggleSection({ hazard, disabled }) {
const otherProps =
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import {
damageSourceStateEffect,
damageTypeState,
} from 'state/data-selection/damage-mapping/damage-map';
import { HAZARDS_METADATA, HAZARDS_UI_ORDER } from 'config/view-layers/hazards/metadata';
import { HAZARDS_METADATA, HAZARDS_UI_ORDER } from 'config/data-layers/hazards/metadata';
import { LayerStylePanel } from 'sidebar/ui/LayerStylePanel';

export const DamageSourceControl = () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@ import { FC } from 'react';

import { CheckboxTree } from 'lib/controls/checkbox-tree/CheckboxTree';

import { NETWORK_LAYERS_HIERARCHY } from 'config/view-layers/networks/hierarchy';
import { NETWORK_LAYERS_HIERARCHY } from 'config/data-layers/networks/hierarchy';
import { useRecoilState, useRecoilValue } from 'recoil';
import {
networkTreeCheckboxState,
networkTreeConfig,
networkTreeExpandedState,
} from 'state/data-selection/networks/network-selection';
import { NETWORKS_METADATA } from 'config/view-layers/networks/metadata';
import { NETWORKS_METADATA } from 'config/data-layers/networks/metadata';
import { LayerLabel } from 'sidebar/ui/LayerLabel';
import { showAdaptationsState } from 'state/layers/data-layers/networks';
import { Box } from '@mui/system';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { ToggleButtonGroup, ToggleButton } from '@mui/material';
import { useRecoilState } from 'recoil';
import { RegionLevel } from 'config/view-layers/regions/metadata';
import { RegionLevel } from 'config/data-layers/regions/metadata';
import { regionLevelState } from 'state/data-selection/regions';
import { useCallback } from 'react';

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import {
MarineLocationFilterType,
MARINE_LOCATION_FILTERS,
} from 'config/view-layers/marine/domains';
} from 'config/data-layers/marine/domains';
import { ParamChecklist } from 'lib/controls/params/ParamChecklist';
import { useRecoilState } from 'recoil';
import { InputSection } from 'sidebar/ui/InputSection';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { FormControl, FormLabel, Slider } from '@mui/material';
import {
TerrestrialLocationFilterType,
TERRESTRIAL_LOCATION_FILTERS,
} from 'config/view-layers/terrestrial/domains';
} from 'config/data-layers/terrestrial/domains';
import { ParamChecklist } from 'lib/controls/params/ParamChecklist';
import { useRecoilState } from 'recoil';
import { InputSection } from 'sidebar/ui/InputSection';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { TERRESTRIAL_LANDUSE_COLORS } from 'config/view-layers/terrestrial/colors';
import { LANDUSE_HIERARCHY } from 'config/view-layers/terrestrial/landuse-hierarchy';
import { TERRESTRIAL_LANDUSE_COLORS } from 'config/data-layers/terrestrial/colors';
import { LANDUSE_HIERARCHY } from 'config/data-layers/terrestrial/landuse-hierarchy';
import { CheckboxTree } from 'lib/controls/checkbox-tree/CheckboxTree';
import { useRecoilState } from 'recoil';
import { LayerLabel } from 'sidebar/ui/LayerLabel';
Expand Down
4 changes: 2 additions & 2 deletions frontend/src/state/data-params.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { HAZARD_DOMAINS } from 'config/view-layers/hazards/domains';
import { NETWORK_DOMAINS } from 'config/view-layers/networks/domains';
import { HAZARD_DOMAINS } from 'config/data-layers/hazards/domains';
import { NETWORK_DOMAINS } from 'config/data-layers/networks/domains';
import {
DataParamGroupConfig,
Param,
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import forEach from 'lodash/forEach';
import { atom, selector } from 'recoil';

import { HAZARD_DOMAINS } from 'config/view-layers/hazards/domains';
import { HAZARD_DOMAINS } from 'config/data-layers/hazards/domains';
import { dataParamOptionsState, dataParamState } from 'state/data-params';
import { hazardSelectionState } from 'state/data-selection/hazards/hazard-selection';
import { networksStyleState } from 'state/data-selection/networks/networks-style';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { damageSourceState, damageTypeState } from './damage-map';
import { dataParamsByGroupState } from 'state/data-params';
import { selector } from 'recoil';
import { FieldSpec, StyleParams } from 'lib/data-map/view-layers';
import { damages } from 'config/view-layers/networks/color-maps';
import { damages } from 'config/data-layers/networks/color-maps';

export const damagesFieldState = selector<FieldSpec>({
key: 'eadAccessorState',
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { DroughtOptionsVariableType } from 'config/view-layers/droughtOptions/metadata';
import { DroughtRiskVariableType } from 'config/view-layers/droughtRisks/metadata';
import { DroughtOptionsVariableType } from 'config/data-layers/droughtOptions/metadata';
import { DroughtRiskVariableType } from 'config/data-layers/droughtRisks/metadata';
import { atom } from 'recoil';

export const droughtRcpParamState = atom<string>({
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { selector } from 'recoil';

import { HAZARDS_MAP_ORDER } from 'config/view-layers/hazards/metadata';
import { HAZARDS_MAP_ORDER } from 'config/data-layers/hazards/metadata';
import {
damageSourceState,
showDamagesState,
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { NETWORK_LAYERS_HIERARCHY } from 'config/view-layers/networks/hierarchy';
import { NETWORK_LAYERS_HIERARCHY } from 'config/data-layers/networks/hierarchy';
import { buildTreeConfig, CheckboxTreeState } from 'lib/controls/checkbox-tree/CheckboxTree';
import mapValues from 'lodash/mapValues';
import { atom, selector } from 'recoil';
Expand Down
2 changes: 1 addition & 1 deletion frontend/src/state/data-selection/regions.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { RegionLevel } from 'config/view-layers/regions/metadata';
import { RegionLevel } from 'config/data-layers/regions/metadata';
import { atom, selector } from 'recoil';
import { sectionStyleValueState } from '../sections';

Expand Down
4 changes: 2 additions & 2 deletions frontend/src/state/data-selection/solutions/landuse-tree.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { LANDUSE_HIERARCHY } from 'config/view-layers/terrestrial/landuse-hierarchy';
import { LandUseOption } from 'config/view-layers/terrestrial/domains';
import { LANDUSE_HIERARCHY } from 'config/data-layers/terrestrial/landuse-hierarchy';
import { LandUseOption } from 'config/data-layers/terrestrial/domains';
import { buildTreeConfig, CheckboxTreeState } from 'lib/controls/checkbox-tree/CheckboxTree';
import mapValues from 'lodash/mapValues';
import pickBy from 'lodash/pickBy';
Expand Down
Loading

0 comments on commit 1fbf59b

Please sign in to comment.