BaseAppLib Project Documentation

Overview

BaseAppLib is the foundational library suite for the MagicPets multi-tenant SaaS platform. It provides shared MVVM architecture, UI components, and infrastructure services that are consumed by AdminApp, StoreApp, and ConsumerApp. Built on .NET 9.0, it implements a modular package-based architecture with Blazor components that work across both WebAssembly and MAUI platforms.

Project Structure

BaseAppLib/
├── BaseApp.ViewModels/          # Core MVVM framework (NuGet package)
├── BaseApp.BlazorUI/            # Core Blazor components (NuGet package)
├── ViewModels/                  # Application-specific ViewModels
├── BlazorUI/                    # Application-specific Blazor components
├── WASMApp/                     # Blazor WebAssembly application
├── MAUIApp/                     # .NET MAUI mobile/desktop app
├── LzAppLoading/                # Loading animation component (package)
├── LzAppConsole/                # Console integration component (package)
├── Blazorise.Icons.FontAwesome/ # FontAwesome icon provider (package)
└── MakePackage.targets          # Build automation

Architecture

Foundation Layer Design

BaseAppLib serves as the foundation layer in a hierarchical architecture:

┌─────────────────────────────────────────┐
│     AdminApp / StoreApp / ConsumerApp   │ ← Consumer Applications
├─────────────────────────────────────────┤
│       Application-Specific Layers       │ ← App-specific ViewModels & UI
├─────────────────────────────────────────┤
│         BaseApp.* Libraries             │ ← Shared Foundation Layer
├─────────────────────────────────────────┤
│         LazyMagic Framework             │ ← Infrastructure Layer
└─────────────────────────────────────────┘

Core Principles

• MVVM Architecture: Built on ReactiveUI with automatic property change notifications
• Multi-Platform Support: Single codebase for Web (WASM) and Mobile/Desktop (MAUI)
• Package Distribution: Core libraries distributed as versioned NuGet packages
• Code Generation: Extensive use of source generators for factories and models
• Multi-Tenancy: Built-in tenant configuration and isolation

Core Package Libraries

BaseApp.ViewModels

Purpose: Provides the core MVVM framework and shared business logic ViewModels.

Key Classes:

Session Management Foundation

• BaseAppSessionViewModel: Abstract base class for user sessions with authentication support
• IBaseAppSessionViewModel: Interface defining session capabilities and lifecycle
• BaseAppSessionsViewModel<T>: Generic base class for managing collections of sessions
• IBaseAppSessionsViewModel<T>: Interface for session collection management

Domain ViewModels

• PetViewModel: Individual pet management with CRUD operations and validation
• PetsViewModel: Collection management for pets with filtering and search
• CategoryViewModel/CategoriesViewModel: Pet category management hierarchy
• TagViewModel/TagsViewModel: Pet tag management with multiple selection

Configuration and Utilities

• TenantConfigViewModel: Tenant-specific configuration management
• TenantConfig: Data transfer object for tenant settings
• BrowserFingerprint: Client identification for security and analytics
• MethodExtensions: Utility methods for dynamic method invocation
• ConfigureBaseAppViewModels: Dependency injection configuration

Key Features:

• Reactive Programming: Built on ReactiveUI for automatic UI updates
• Factory Pattern: Auto-generated factories for ViewModel creation
• Authentication Integration: Built-in support for Cognito authentication
• Multi-Tenant Support: Tenant-aware ViewModels with configuration management
• Code Generation: Uses [Factory] and [Reactive] attributes for automation

Dependencies:

• ReactiveUI (reactive programming framework)
• LazyMagic framework (code generation and utilities)
• FluentValidation (data validation)
• API client interfaces (for backend communication)

BaseApp.BlazorUI

Purpose: Provides core Blazor components and UI infrastructure shared across applications.

Key Components:

Pet Domain Components

• Pet.razor: Basic pet display component with minimal styling
• PetsList.razor: Pet collection display using MudTable with sorting and pagination
• CategorySelect.razor: Category selection dropdown with hierarchical support
• TagsSelect.razor: Multi-select tag component with search functionality
• PetStatusSelect.razor: Pet status selection with predefined values

System Components

• AppInfo.razor: Application information dialog with version and build details
• AppUpdates.razor: Update notification component for new releases
• Busy.razor: Loading indicator with CSS animations and customizable messaging
• OnLine.razor: Connectivity status indicator with real-time updates
• SignedIn.razor: Authentication status display with user information
• LanguageSelect.razor: Multi-language selection component

Infrastructure

• ConfigureBaseAppBlazorUI: Service registration for Blazor components
• ConfigureBaseAppMessages: Internationalization and messaging setup
• WindowSize.cs: Browser window size tracking and responsive behavior

Key Features:

• MudBlazor Integration: Material Design components with consistent theming
• Responsive Design: Components adapt to different screen sizes
• Accessibility: ARIA labels and keyboard navigation support
• Multi-Language Support: Built-in internationalization framework
• Theme Support: Light/dark mode with customizable color palettes

Dependencies:

• BaseApp.ViewModels (for data binding)
• MudBlazor (UI component library)
• LazyMagic.OIDC (Authentication libraries)
• KristofferStrube.Blazor.FileSystemAccess (file operations)

Specialized Libraries

LzAppLoading

Purpose: Animated loading screen component with customizable progress indicators.

Key Classes:

• LzAppLoading.razor: Main loading component with SVG-based circular progress
• LzAppLoading.razor.css: CSS animations for smooth progress transitions

Features:

• Configurable Animation: Duration, acceleration, and easing controls
• Progress Tracking: Real-time progress updates with percentage display
• JavaScript Interop: Browser integration for performance optimization
• Completion Callbacks: Event handling for loading completion

Usage Example:

<LzAppLoading Duration="3000" ShowProgress="true" OnCompleted="@HandleLoadComplete" />

LzAppConsole

Purpose: Browser console integration for debugging and diagnostics.

Key Classes:

• LzConsole.razor: Console component with JavaScript interop
• LzConsoleInterop.cs: JavaScript bridge for console operations

Features:

• Console Logging: Write messages to browser console from Blazor
• Event Handling: Capture and process console events
• Disposal Pattern: Proper cleanup of JavaScript resources
• Debug Support: Enhanced debugging capabilities for development

Blazorise.Icons.FontAwesome

Purpose: Complete FontAwesome 6 icon provider for Blazorise components.

Key Classes:

• FontAwesomeIconProvider.cs: Icon mapping implementation with 2000+ icons
• FontAwesomeIcons.cs: Static icon constant definitions
• Icon.razor: Custom icon component with styling support

Features:

• Complete Icon Library: All FontAwesome 6 icons (solid, regular, light, duotone)
• Type Safety: Strongly-typed icon constants
• Style Support: Multiple icon styles and weights
• Performance Optimized: Efficient icon rendering and caching

Application-Specific Projects

ViewModels Project

Purpose: Application-specific ViewModels that extend BaseApp.ViewModels for concrete implementations.

Key Classes:

• SessionViewModel: Concrete implementation of session management with API integration
• SessionsViewModel: Global application state management
• ICurrentSessionViewModel: Interface for accessing current active session
• ConfigureViewModels: Complete dependency injection setup including API clients

Integration Pattern:

// Extends base classes with application-specific logic
public class SessionViewModel : BaseAppSessionViewModel
{
    // Application-specific session handling
}

BlazorUI Project

Purpose: Application-specific Blazor components that build on BaseApp.BlazorUI.

Key Components:

Layout Components

• MainLayout.razor: Primary application layout with MudBlazor integration

  • Features: App bar, drawer navigation, theme switching, connectivity status
  • Theme: Light/dark mode support with custom color palettes
  • Responsive: Adapts to mobile and desktop screen sizes

• LoadingLayout.razor: Minimal layout for loading states

• NavMenu.razor: Application-specific navigation menu

Application Pages

• HomePage.razor: Application home page with authentication integration
• PetPage.razor: Individual pet management and viewing
• PetsPage.razor: Pet listing with search, filter, and pagination

Core Components

• Main.razor: Application root component with router and initialization
• Config/ConfigureBlazorUI: Service registration and configuration

WASMApp Project

Purpose: Blazor WebAssembly application for web deployment.

Key Features:

• Progressive Web App (PWA): Service worker support for offline capabilities
• Environment Configuration: Automatic detection of local vs. production environments
• Performance Optimization: Trimming and compression for faster loading
• JavaScript Interop: Browser integration for configuration and assets

MAUIApp Project

Purpose: .NET MAUI hybrid application for cross-platform deployment.

Supported Platforms:

• Android (net9.0-android)
• iOS (net9.0-ios)
• macOS Catalyst (net9.0-maccatalyst)
• Windows (net9.0-windows10.0.19041.0)

Key Features:

• Native Integration: Platform-specific APIs and capabilities
• Embedded WebView: Hosts Blazor components in native app container
• Resource Management: Embedded assets and platform-specific configurations
• App Lifecycle: Native app lifecycle integration with Blazor components

MVVM Framework Implementation

ReactiveUI Foundation

BaseAppLib builds on ReactiveUI to provide a robust MVVM framework:

Base Classes:

• LzItemViewModelBase<T>: Base class for individual entity ViewModels
• LzItemsViewModelBase<T>: Base class for collection ViewModels
• LzSessionViewModel: Session-aware ViewModels with authentication

Property Management:

// Automatic property change notifications via Fody
[Reactive] public string Name { get; set; }

// Reactive commands for async operations
public ReactiveCommand<Unit, Unit> SaveCommand { get; }

Factory Pattern Integration

Code generation creates factories for dependency injection:

[Factory]
public class PetViewModel : LzItemViewModel<Pet, PetModel>
{
    public PetViewModel(
        [FactoryInject] ILogger<PetViewModel> logger,
        [FactoryInject] IPetApi petApi,
        // ... other dependencies
    )
}

// Auto-generated factory
public interface IPetViewModelFactory
{
    PetViewModel Create(/* parameters */);
}

Authentication Integration

Built-in support for Cognito authentication:

public class SessionViewModel : BaseAppSessionViewModel
{
    public IAuthProcess AuthProcess { get; }
    
    // Automatic authentication state management
    public bool IsSignedIn => AuthProcess.IsSignedIn;
}

Configuration and Dependency Injection

Service Registration Pattern

BaseAppLib provides extension methods for clean service registration:

public static IServiceCollection AddBaseAppViewModels(this IServiceCollection services)
{
    // Register base framework services
    BaseAppViewModelsRegisterFactories.BaseAppViewModelsRegister(services);
    services.TryAddSingleton<ILzMessages, LzMessages>();
    services.AddLazyMagicAuthCognito();
    return services;
}

public static IServiceCollection AddBaseAppBlazorUI(this IServiceCollection services)
{
    // Register Blazor components and services
    services.AddMudServices();
    services.TryAddSingleton<IStaticAssets, StaticAssets>();
    return services;
}

Multi-Platform Configuration

Different configuration strategies for different platforms:

WASM Configuration:

// Browser-based configuration via JavaScript
var config = await JSRuntime.InvokeAsync<TenantConfig>("getAppConfig");

MAUI Configuration:

// Embedded resource configuration
var configStream = await FileSystem.OpenAppPackageFileAsync("tenantconfig.json");

Tenant Management

Built-in multi-tenancy support:

public class TenantConfigViewModel : LzItemViewModelBase<TenantConfig>
{
    // Tenant-specific configuration
    public string TenantName { get; set; }
    public Dictionary<string, object> AuthConfigs { get; set; }
    public AssetConfig Assets { get; set; }
}

Integration Points

API Communication

Standardized API integration patterns:

// Module client integration
services.AddSingleton<IPublicModuleClient>(provider => 
    provider.GetService<IPublicApi>()!.PublicModuleClient);

// HTTP client configuration
services.AddHttpClient<ApiClient>(client =>
{
    client.BaseAddress = new Uri(apiBaseUrl);
    client.DefaultRequestHeaders.Add("User-Agent", "MagicPets-Client");
});

State Management

Global application state via reactive ViewModels:

// singleton current session
services.Add<ISessionViewModel, SessionViewModel>();

Asset Management

Dynamic asset loading with tenant support:

public interface IStaticAssets
{
    Task<T> GetAsync<T>(string path, string? tenant = null);
    Task<string> GetStringAsync(string path, string? tenant = null);
}

Benefits for Consumer Applications

Code Reuse

BaseAppLib enables significant code reuse across AdminApp, StoreApp, and ConsumerApp:

• Shared UI Components: Consistent look and feel
• Common ViewModels: Pet management, session handling
• Authentication: Unified auth patterns
• Configuration: Multi-tenant support

Consistency

• Design System: Material Design via MudBlazor
• Interaction Patterns: Consistent user experience
• Data Flow: Standardized MVVM patterns
• Error Handling: Unified error management

Maintainability

• Single Source of Truth: Base functionality in one place
• Version Management: Package-based distribution
• Testing: Shared test utilities and patterns
• Documentation: Centralized documentation

Scalability

• Performance: Optimized components and patterns
• Multi-Platform: Single codebase for web and mobile
• Multi-Tenant: Built-in tenant isolation
• Extensibility: Plugin-based architecture

Development Workflow

Building Packages

cd BaseAppLib
dotnet build
# Creates versioned NuGet packages in /Packages/

Running Demo Applications

# Web version
cd WASMApp
dotnet run

# Mobile version
cd MAUIApp
dotnet build -f net9.0-windows10.0.19041.0

Package Distribution

# Packages are automatically versioned and built
# Format: {PackageName}.{Version}.nupkg
# Example: BaseApp.ViewModels.1.3.0.nupkg

Architectural Strengths

1. Modular Design: Clean separation of concerns with package-based distribution
2. Framework Integration: Deep integration with ReactiveUI, MudBlazor, and .NET MAUI
3. Code Generation: Extensive automation reduces boilerplate code
4. Multi-Platform: Single codebase supports web, mobile, and desktop
5. Multi-Tenant: Built-in tenant isolation and configuration
6. Reactive Architecture: Real-time UI updates with minimal code
7. Type Safety: Strong typing throughout the framework
8. Performance: Optimized for both development experience and runtime performance

BaseAppLib serves as the solid foundation that enables rapid development of the AdminApp, StoreApp, and ConsumerApp while maintaining consistency, quality, and performance across the entire MagicPets platform.