Architecture Diagrams

Simplified visual diagrams of how the AquaGen web app is put together. Each diagram is followed by a one-line summary of what it shows.

Read alongside the Applications section

These diagrams show the shared architecture of the main production app. The repo actually builds five apps (AquaGen, AquaRecycle, Lakepulse, AquaRain, and a demo) — see Applications → Overview. Module Federation is turned off, so anything implying runtime feature-loading is not active today.

Diagrams adapt to light & dark mode

Coloured boxes use white text on a solid fill so they stay readable in both themes. If a diagram ever looks off, toggle the site theme and refresh.

---

1. High-Level System Architecture

Summary: The React browser app calls Azure REST APIs over Axios (with a JWT); Azure AD, Google OAuth, Web PubSub, analytics, and Firebase hosting are the external services around it.

---

2. Application Bootstrap Flow

Summary: main.jsx loads bootstrap.jsx, which initialises services and wraps the app in a fixed provider chain — Google OAuth → MSAL → MUI theme → AppStore → Router — before rendering.

---

3. Nx Monorepo Structure

Summary: One Nx monorepo builds 5 apps from 30 shared libraries, layered as feature libs → components → shared foundation. Full inventory in Libraries & Modules.

---

4. Dependency Rules (import direction)

Summary: Imports flow one way — apps → features → components → shared. Features must not import each other, and components must not reach into features. (These are the intended rules; see Libraries → Dependency rules for the real-world exceptions.)

---

5. Feature Library Internal Structure

Summary: Every feature lib has the same four layers — dataSource (API) → controller (logic) → store (Context state) → components (UI) — with the page component tying them together.

---

6. Data Flow (request round-trip)

Summary: Data flows down Component → Store → Controller → DataSource → apiClient → Backend and the response comes back up the same chain, ending in a re-render. (Sequence diagrams follow the site theme automatically.)

---

7. Authentication Flow

Summary: On launch the app checks LocalDB for a token; if missing it signs in via Microsoft or Google, stores the returned JWT, and attaches it to every later request. A 440 clears the session; a 420 sends the user home.

---

8. Routing (top level)

Summary: Public /splash and /login sit outside the app shell; everything else renders inside the authenticated MainLayout. The canonical, complete route list lives in Features → Routes.

---

9. Shared Library (libs/shared/src/)

Summary: shared is the foundation every app depends on: the API client and other services, the global AppStore, config/constants, enums, hooks, and utilities. Details in Libraries & Modules.

---

10. Build & Deployment Pipeline

Summary: Rspack builds each app to dist/apps/<app>. The main production app ships to Azure via CI (real prod); every app can also deploy to Firebase (~21 dev/test/prod targets) via deploy.sh. See Deployment & Environments.

---

11. Component Library (libs/components/src/)

Summary: The shared components library groups roughly 35 categories of reusable UI — navigation, inputs, layouts/pages, charts, and media — reused across every app.

---

12. API Client (apiClient.js)

Summary: A single Axios instance adds a raw JWT (no Bearer) plus device headers on every request, and on the way back handles only 440 (clear login → /login) and 420 (→ /), throwing everything else to the caller. Full detail in API Call Flow.

---

13. State Management

Summary: State is split two ways — one global AppStore (auth, nav, UI, date) plus a per-feature Context store in each lib — with auth tokens and caches persisted in LocalDB. See State Management.

---

14. Security Layers

Summary: Defence in depth — browser security headers, then Azure AD/Google/JWT auth, device fingerprinting, per-request Authorization over HTTPS, and analytics (recorded on production builds only). The exact headers and full CSP are documented in Configuration & Security.

---

15. Mobile (Capacitor)

Summary: The same React SPA is wrapped by Capacitor to ship as native iOS and Android apps in addition to the web build.

---

Quick reference: key files

Area	File	Purpose
Entry	apps/production/src/main.jsx	App entry
	apps/production/src/bootstrap.jsx	Provider setup
	apps/production/src/routes/routes.js	All routes
Config	apps/production/rspack.config.js	Bundler config
	firebase.json · .firebaserc	Hosting targets & sites
	tsconfig.base.json	Import path aliases
Shared	libs/shared/src/services/api/apiClient.js	API client
	libs/shared/src/store/AppStore.js	Global state
	libs/shared/src/constants/constants.js	Env flags & constants
Deploy	bash-scripts/deploy.sh · deploy-app.sh	Firebase deploys

---

Next steps

• Applications → Overview — the five apps and how they relate
• Micro-Frontend Architecture — architecture deep dive
• Libraries & Modules — the shared library inventory
• API Call Flow — request/response detail
• Configuration & Security — constants.js and the CSP / security headers
• Deployment & Environments — how each app ships