Libraries & Modules

Every app in the monorepo (see Applications) is built from a shared set of libraries under libs/. This page is the inventory: what each library is, who uses it, and the rules that (mostly) govern how they depend on each other.

The import naming scope

All libraries are imported through the @aquagen-mf-webapp/<name> path alias, declared in the root tsconfig.base.json:

import { AppStoreContext } from '@aquagen-mf-webapp/shared/store/AppStore';
import { MainLayout } from '@aquagen-mf-webapp/components/pages/layouts/MainLayout';

The mf in the scope stands for Module Federation, which the project was originally built around but no longer uses. The name stuck.

Aliases live in two places

The root tsconfig.base.json is the authoritative alias list, but each app also declares aliases in its own rspack.config.js and tsconfig.json. A few libraries (notably aquaAi) resolve only through the per-app configs and are missing from the root file.

Master inventory

Legend for Status: ✅ active · 🟡 superseded-but-used · 🟠 orphaned · 🔴 dead. Orphaned/dead libraries are explained in Legacy & Deprecated.

Foundation

Library	Import alias	Purpose	Used by	Status
`shared`	`@aquagen-mf-webapp/shared`	Core services, store, hooks, utils, constants	Everything	✅
`components`	`@aquagen-mf-webapp/components`	Shared UI component library (buttons, graphs, layouts, nav)	Everything	✅
`uilib`	`@aquagen-mf-webapp/uilib`	Nx-generated placeholder	Nobody	🟠

Sustainability indices

Library	Import alias	Purpose	Used by	Status
`uwi`	`@aquagen-mf-webapp/uwi`	Urban Water Index	production, demo, uwms	✅
`rwi`	`@aquagen-mf-webapp/rwi`	Rainwater Index	production, demo, rwi	✅
`gwi`	`@aquagen-mf-webapp/gwi`	Ground Water Index	production, demo	✅
`waterRisk`	`@aquagen-mf-webapp/waterRisk`	Water-risk prediction	Nobody (not routed)	🟠

Feature libraries

Library	Import alias	Purpose	Used by	Status
`monitoring`	`@aquagen-mf-webapp/monitoring`	Core water monitoring (largest feature lib)	prod, demo, uwms, rwi	✅
`dashboard`	`@aquagen-mf-webapp/dashboard`	Main dashboard	production, demo	✅
`leadership`	`@aquagen-mf-webapp/leadership`	Executive dashboard	production, demo	✅
`energy`	`@aquagen-mf-webapp/energy`	Energy monitoring	production, demo	✅
`alerts`	`@aquagen-mf-webapp/alerts`	Alerts & notifications	All 5 apps	✅
`manageAccount`	`@aquagen-mf-webapp/manageAccount`	Account & settings	All 5 apps	✅
`aquaAi`	`@aquagen-mf-webapp/aquaAi`	AI assistant (project name `ecogpt`)	All 5 apps	✅
`featureLocked`	`@aquagen-mf-webapp/featureLocked`	Paywall / upsell for locked features	All 5 apps	✅
`waterBalance`	`@aquagen-mf-webapp/waterBalance`	Water balance	production, demo	✅
`waterNeutrality`	`@aquagen-mf-webapp/waterNeutrality`	Water neutrality	production, demo	✅
`waterRatio`	`@aquagen-mf-webapp/waterRatio`	Water usage ratio (project name `waterUsage`)	production, demo	✅
`roEfficiency`	`@aquagen-mf-webapp/roEfficiency`	RO (reverse-osmosis) efficiency	production, demo	✅
`ilm`	`@aquagen-mf-webapp/ilm`	Lake / water-quality (satellite, heatmap)	production, demo, lakepulse	✅
`hmi`	`@aquagen-mf-webapp/hmi`	Human-Machine Interface	production, demo	✅
`scadaEditor`	`@aquagen-mf-webapp/scadaEditor`	SCADA diagram editor	production, demo	✅
`scadaViewer`	`@aquagen-mf-webapp/scadaViewer`	SCADA diagram viewer	production, demo	✅
`aquagenLabs`	`@aquagen-mf-webapp/aquagenLabs`	Experimental "Labs" features	production, demo	✅
`trueCost`	`@aquagen-mf-webapp/trueCost`	True cost of water	demo only	✅
`reportsV2`	`@aquagen-mf-webapp/reportsV2`	Reports (v2 — with store & subpages)	production, demo	✅
`reports`	`@aquagen-mf-webapp/reports`	Reports (v1)	uwms, lakepulse, rwi	🟡
`aquagpt`	`@aquagen-mf-webapp/aquagpt`	GPT chat assistant	Nobody	🟠
`demoAquaGpt`	`@aquagen-mf-webapp/demoAquaGpt`	Mock GPT chat (dummy data)	Nobody	🟠
`legacyReports`	— (none)	Empty skeleton	Nobody	🔴

Two phantom aliases also exist in tsconfig.base.json — pricing and wri — that point at folders which do not exist. See Legacy & Deprecated.

The reports libraries

There are three reports libraries; only two are alive:

Library	Used by	Notes
`reportsV2`	AquaGen, Demo	Current version — has its own store and subpages
`reports` (v1)	AquaRecycle, Lakepulse, AquaRain	Older, still active in the standalone apps
`legacyReports`	nobody	🔴 Empty — the pre-v1 remnant

So reports v1 and reportsV2 coexist by app tier: the flagship apps use v2, the standalone apps use v1. Moving the standalone apps onto reportsV2 and deleting v1 + legacyReports is a future cleanup.

Which apps use which libraries

Every app shares a common baseline, then adds its own feature libraries.

Baseline (all 5 apps): shared, components, manageAccount, alerts, aquaAi, featureLocked.

App	Adds
`production`	The full catalog — monitoring, dashboard, leadership, energy, all indices, water balance/neutrality/ratio, roEfficiency, hmi, scada×2, ilm, aquagenLabs, `reportsV2`
`demo`	Same as production + `trueCost`
`uwms` (AquaRecycle)	`monitoring`, `uwi`, `reports` (v1)
`lakepulse` (Lakepulse)	`ilm`, `reports` (v1) — no `monitoring`
`rwi` (AquaRain)	`monitoring`, `rwi`, `reports` (v1)

Dependency rules and where they break

The intended layering is shared → components → features (features are leaves; foundation never imports features). It holds as intent, but there are real violations to be aware of:

shared ↔ components cycle. shared imports components in ~12 places (for example, AppStore.js imports the login controller), while components imports shared heavily. The two foundation libraries depend on each other.
components reaches into features. components imports from dashboard, monitoring, and energy (for example, MainLayout imports monitoring's store) — a foundation library reaching up into features.
Feature ↔ feature imports. Several features import each other: dashboard → uwi, ilm → gwi, monitoring → aquagenLabs, roEfficiency → dashboard, plus two cycles — scadaEditor ↔ scadaViewer and scadaViewer ↔ uwi.

None of these break the build, but they mean the layering is not enforced. Treat the rule as a guideline, and avoid adding new cross-feature or foundation-to-feature edges.

Library folder convention

New libraries are created with npm run create:lib <name>, which produces this structure. Most feature libraries follow it, though folder names vary (e.g. enum vs enums) and some libs omit helper or enum:

libs/<feature>/
├── src/
│   ├── components/     # feature-specific UI
│   ├── controller/     # business logic
│   ├── dataSource/     # API calls
│   ├── store/          # state (React Context)
│   ├── enum/           # constants and enums (some libs use enums/)
│   ├── helper/         # utility functions
│   └── <Feature>Page.jsx  # the main page component

This maps to the app's design patterns — see Architecture → Micro-Frontend Architecture and API Call Flow.

Naming oddities

A few libraries have folder names and internal project names that don't match. Keep this handy when reading project.json files:

Folder	`project.json` name	What it is
`aquaAi`	`ecogpt`	The current AI assistant
`rwi`	`rwi-lib`	Rainwater Index feature
`waterRatio`	`waterUsage`	Water usage ratio

(The aquagpt / demoAquaGpt / aquaAi trio is the easiest place to get lost: aquaAi — confusingly named ecogpt — is the live one; the other two are orphaned.)

Next steps

Applications → Overview — how these libraries combine into apps.
Applications → Legacy & Deprecated — the orphaned and dead libraries.
Micro-Frontend Architecture — the monorepo and design patterns.

The import naming scope​

Categories​

Master inventory​

Foundation​

Sustainability indices​

Feature libraries​

The reports libraries​

Which apps use which libraries​

Dependency rules and where they break​

Library folder convention​

Naming oddities​

Next steps​