Skip to main content

Introduction to AquaGen Web Application

Welcome to the AquaGen Web Application documentation. This section covers everything you need to know to get started with the platform.

📚 Documentation Contents​

1. Architecture Diagrams​

What you'll learn:

  • High-level system architecture diagram
  • Application bootstrap flow (5-level provider chain)
  • Nx monorepo structure with all 27 libraries
  • Dependency flow and import rules
  • Feature library internal architecture pattern
  • Complete data flow (Component → Store → Controller → DataSource → API)
  • Authentication flow (Azure AD + Google OAuth)
  • Routing architecture (all routes mapped)
  • Shared library internals
  • Build and deployment pipeline
  • Component library overview (39 categories)
  • API architecture (interceptors, endpoints, environments)
  • State management overview (Global + Feature stores)
  • Security layers (5 layers)
  • Mobile architecture (Capacitor)
  • Key files quick reference

Start here if: You want a visual overview of the entire system before diving into details.

2. Overview​

What you'll learn:

  • What is AquaGen and its purpose
  • Key features and capabilities
  • Complete technology stack
  • All application modules (25+ features)
  • Architecture highlights
  • Browser and mobile support
  • Performance and security features

Start here if: You're new to the project and want to understand what AquaGen does.

3. Installation​

What you'll learn:

  • Prerequisites (Node.js, npm, Git)
  • Step-by-step installation guide
  • Environment configuration
    • Firebase setup
    • Azure AD authentication
    • API endpoints
  • Verification steps
  • Common installation issues and solutions

Start here if: You need to set up your development environment.

4. Micro-Frontend Architecture​

What you'll learn:

  • Micro-frontend architecture concepts
  • Nx monorepo structure
  • Module Federation setup (ready to enable)
  • Rspack bundler configuration
  • Apps vs Libraries organization
  • Dependency rules and constraints
  • Design patterns (Controller, DataSource, Store)
  • Routing architecture
  • Build process details

Start here if: You want to understand the technical architecture and design decisions.

5. Commands Reference​

What you'll learn:

  • All npm scripts explained
    • Development (npm start, npm run start:app)
    • Build (npm run build, npm run build:app)
    • Project management (npm run create:lib, npm run integrate:lib)
    • Deployment (npm run deploy:app)
  • Nx commands (build, serve, test, lint, generate)
  • Git workflow commands
  • Firebase commands
  • Environment variables
  • Quick reference cheat sheet

Start here if: You need to know what commands are available and how to use them.

6. Deployment​

What you'll learn:

  • Firebase Hosting setup
  • Complete deployment process
  • All 14 hosting targets (uat, test1-9, demo, pre-prod, dev, aquagen)
  • Security headers and CSP configuration
  • Rollback strategies
  • CI/CD with GitHub Actions
  • Custom domain setup
  • Performance optimization
  • Troubleshooting deployment issues
  • Deployment checklist

Start here if: You need to deploy the application to Firebase hosting.

🚀 Quick Start Path​

For New Developers​

  1. Read Overview - Understand what AquaGen is
  2. Follow Installation - Set up your environment
  3. Review Commands Reference - Learn the essential commands
  4. Start coding!

For Architects​

  1. Read Overview - Understand the platform
  2. Study Micro-Frontend Architecture - Deep dive into design
  3. Review Commands Reference - Understand build tooling
  4. Plan your implementation

For DevOps Engineers​

  1. Read Installation - Understand setup requirements
  2. Study Deployment - Learn deployment process
  3. Review Commands Reference - Understand build commands
  4. Set up CI/CD pipelines

📁 Project Structure Overview​

aquagen_web_appp/
├── apps/                    # Applications
│   ├── production/         # Main production app
│   ├── demo/              # Demo app
│   └── *-e2e/            # E2E test apps
├── libs/                   # Feature libraries
│   ├── dashboard/         # Dashboard module
│   ├── monitoring/        # Monitoring module
│   ├── energy/           # Energy module
│   ├── aquagpt/          # AI-powered insights
│   ├── shared/           # Shared utilities
│   ├── components/       # Reusable UI components
│   └── ... (20+ more)
├── docs/                  # Documentation (you are here!)
│   └── Introduction/     # Getting started docs
├── package.json          # Dependencies and scripts
├── nx.json              # Nx workspace configuration
└── firebase.json        # Firebase hosting config

🔑 Key Concepts​

Nx Monorepo​

A single repository containing multiple applications and libraries, managed by Nx for efficient builds and dependency management.

Micro-Frontend Architecture​

The application is split into independent feature modules that can be developed, tested, and potentially deployed separately.

Module Federation​

Advanced build configuration (ready to enable) that allows dynamic loading of feature modules at runtime.

Feature Libraries​

Self-contained modules with business logic, organized with:

  • Components - UI components
  • Controller - Business logic
  • DataSource - API integration
  • Store - State management
  • Helpers - Utility functions
  • Enums - Constants

🛠️ Technology Stack​

CategoryTechnologies
FrontendReact 19, Material-UI 7, TypeScript 5.7
Build ToolsNx 21, Rspack 1.3, Module Federation
State ManagementReact Context, Custom Hooks
Data VisualizationChart.js, Recharts, Plotly.js, Leaflet
AuthenticationAzure MSAL, Google OAuth
TestingJest, Cypress, Playwright
DeploymentFirebase Hosting, Capacitor (Mobile)
MonitoringSentry, Mixpanel, Google Analytics 4

📖 Additional Documentation​

Beyond this Introduction section, additional documentation covers:

  • Libraries & Components - Detailed docs for each feature library
  • APIs & Data Flow - How data flows through the application
  • Development Workflow - Daily development tasks and best practices
  • Testing Strategy - Unit, integration, and E2E testing
  • Troubleshooting - Common issues and solutions
  • FAQ - Frequently asked questions

🎯 Learning Path​

Week 1: Getting Started​

Week 2: Development​

  • Study Commands Reference
  • Create a test library (npm run create:lib)
  • Make a small code change
  • Build the application (npm run build)
  • Understand the feature architecture pattern

Week 3: Deployment​

  • Read Deployment
  • Deploy to test environment
  • Learn Firebase hosting configuration
  • Understand security headers and CSP

Week 4+: Advanced Topics​

  • Deep dive into specific libraries
  • Learn testing strategies
  • Explore API integration patterns
  • Contribute to the project

💡 Tips for Success​

  1. Start with the basics - Don't skip Installation
  2. Use the commands reference - Keep Commands Reference handy
  3. Understand the architecture - Read Micro-Frontend Architecture before coding
  4. Follow the patterns - All features use Controller/DataSource/Store pattern
  5. Test locally before deploying - Always test builds with npm run serve:build
  6. Ask questions - If something is unclear, refer back to this documentation

🔗 Quick Links​

📝 Documentation Format​

Each document follows this structure:

  • Clear headings - Easy navigation
  • Code examples - Practical demonstrations
  • Step-by-step instructions - For complex tasks
  • Troubleshooting sections - Common issues and solutions
  • Cross-references - Links to related documentation

Ready to get started? Begin with Overview or jump straight to Installation!

Last Updated: February 2026 Maintained By: AquaGen Development Team