LazyMagic

StoreApp Project Documentation

Overview

StoreApp is a multi-platform store management interface for the MagicPets system, designed specifically for store employees to manage pet inventory and store operations. Built using the same Blazor + MVVM architecture as AdminApp, it supports both web deployment (Blazor WebAssembly) and cross-platform mobile/desktop deployment (.NET MAUI) with a shared UI codebase.

Project Structure

StoreApp/
├── ViewModels/          # MVVM business logic layer
├── BlazorUI/            # Shared Razor components and pages
├── WASMApp/             # Blazor WebAssembly entry point
├── MAUIApp/             # .NET MAUI mobile/desktop entry point
├── Config/              # Configuration project
└── MakeRelease/         # Build and release tooling

Architecture

Multi-Platform Design

  • Web: Blazor WebAssembly deployed at /store/ path
  • Mobile/Desktop: .NET MAUI hybrid app (iOS, Android, Windows, macOS)
  • Shared UI: Single set of Blazor components works across all platforms

Store-Specific Focus

Unlike AdminApp which handles system administration, StoreApp focuses on:

  • Pet inventory management
  • Store-specific operations
  • Employee workflows
  • Customer-facing store activities

Project Components

ViewModels Project

Purpose: Contains the MVVM business logic layer with ViewModels specific to store operations.

Key Classes:

Session Management

  • SessionsViewModel: Root application state manager (singleton) for store sessions
  • SessionViewModel: Individual store employee session with authentication and tenant context
  • ICurrentSessionViewModel: Interface for dependency injection of current session
  • ISessionViewModel: Interface defining session operations
  • ISessionsViewModel: Interface for the root session manager

Configuration

  • ConfigureViewModels: Dependency injection setup for ViewModels and StoreApi clients
  • AppConfig: Static application configuration holder for store settings

Key Differences from AdminApp:

  • Uses StoreApi instead of AdminApi for backend communication
  • Focused on store-specific business logic
  • Configured for store employee authentication scope

Dependencies:

  • BaseApp.ViewModels (base MVVM framework)
  • StoreApi (generated client SDK for store operations)
  • LazyMagic client libraries for authentication and factories

BlazorUI Project

Purpose: Shared Blazor Razor components and pages used by both Web and Mobile applications for store operations.

Key Components:

Layout Components

  • MainLayout.razor: Primary application layout with MudBlazor theming and store-specific navigation
  • NavMenu.razor: Navigation menu tailored for store operations (Home, Pets)
  • Main.razor: Application root component with router and initialization logic

Store-Specific Pages

  • HomePage.razor: Store landing page with authentication component (/)
  • Sessions.razor: Application entry point for store employee sessions
  • PetsPage.razor: Pet inventory management with CRUD operations (/PetsPage)
  • PetEditPage.razor: Form for creating/editing pet records with validation (/PetEditPage)

Configuration

  • ConfigureBlazorUI: Service registration and dependency injection setup for store UI layer

Key Differences from AdminApp:

  • Pet-focused pages instead of user/tenant management
  • Store-specific navigation (Pets vs Users/Subtenants)
  • Store employee workflows rather than administrative tasks

Dependencies:

  • MudBlazor (UI component library)
  • BaseApp.BlazorUI (base UI components)
  • ViewModels project (store business logic)
  • LazyMagic Blazor libraries

WASMApp Project

Purpose: Blazor WebAssembly application entry point for web deployment at /store/ path.

Key Classes:

  • Program: Static entry point that configures WebAssembly host for store operations

Configuration:

  • Deployed at /store/ path (vs /admin/ for AdminApp)
  • Store-specific service worker configuration
  • JavaScript configuration for store context

MAUIApp Project

Purpose: .NET MAUI hybrid application for cross-platform store management.

Target Platforms:

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

Key Classes:

  • App.xaml/App.xaml.cs: MAUI application lifecycle management
  • MainPage.xaml/MainPage.xaml.cs: Primary page hosting Blazor WebView for store interface
  • MauiProgram: Application factory that configures platform-specific services

Data Flow and Communication

Store-Specific Architecture Flow

Entry Point (WASM/MAUI) → Store Service Registration → Store Session Creation → Pet Management → Store API Communication

Communication Pattern

Store UI Components ↔ Store ViewModels ↔ StoreApi Client ↔ Store Backend Services
        ↑                    ↑               ↑
   Data Binding → Store State Mgmt → Store HTTP Calls

Authentication Flow

  • Uses AWS Cognito through LazyMagic authentication libraries
  • TenantAuth system for store employees (same as AdminApp but different scope)
  • Authentication state managed in SessionViewModel.AuthProcess
  • Store-specific authorization and permissions

MVVM Implementation Details

Store-Specific ViewModels

  • Pet Management ViewModels: Auto-generated from StoreSchema for pet operations
  • Store Session Management: Tailored for store employee workflows
  • Inventory Operations: ViewModels for stock management and pet tracking

Factory Pattern

  • ViewModels use [Factory] attribute for automatic code generation
  • Store-specific factories: IStoreSessionViewModelFactory, IPetViewModelFactory
  • Factories registered in DI container for store operations

State Management

  • Store Sessions: Manages store employee login and context
  • Pet Inventory: Real-time updates for pet availability and status
  • Store Operations: State tracking for store-specific workflows

Validation

Multi-level validation for store operations:

  1. StoreSchema DTO validation
  2. Store Model validation in StoreApi client
  3. Local UI validation for store-specific business rules

Key Features

Pet Management

  • Pet Inventory: Complete CRUD operations for pet records
  • Pet Details: Comprehensive pet information management
  • Availability Tracking: Real-time pet availability status
  • Search and Filtering: Advanced pet discovery capabilities

Store Operations

  • Employee Access: Store employee authentication and authorization
  • Multi-Store Support: Tenant-based store isolation
  • Real-Time Updates: Live inventory updates across store interfaces

Cross-Platform Store Access

  • Web Interface: Browser-based store management
  • Mobile Apps: Native mobile apps for on-the-go store operations
  • Desktop Apps: Full-featured desktop applications for store terminals

Configuration

Store-Specific Service Registration

builder.Services.AddAppViewModels();    // Store ViewModels
builder.Services.AddBlazorUI();         // Store UI components

Key Service Registrations

  • ISessionsViewModel: Singleton store session manager
  • ICurrentSessionViewModel: Transient current store session accessor
  • IStoreApi: Singleton instance for store backend communication
  • Store Module Clients: Consumer, Public modules accessible to store operations

Configuration Sources

  • appConfig.js: JavaScript configuration for store web deployment
  • launchSettings.json: Development environment settings for store operations
  • tenantconfig.json: Store-specific tenant configuration
  • Store Assets: Store-specific themes, branding, and resources

Differences from AdminApp

Functional Scope

Aspect StoreApp AdminApp
API Client StoreApi AdminApi
Primary Users Store Employees System Administrators
Main Features Pet Management User/Tenant Management
Navigation Home, Pets Home, Users, Subtenants
Deployment Path /store/ /admin/
Focus Store Operations System Administration

Page Comparison

StoreApp Pages AdminApp Pages
PetsPage.razor UsersPage.razor
PetEditPage.razor UserEditPage.razor
- SubtenantsPage.razor
- SubtenantEditPage.razor

Authentication Scope

  • StoreApp: TenantAuth for store employee operations
  • AdminApp: TenantAuth for system administrative operations

Dependencies on Other Projects

Generated Client SDKs

  • StoreApi: Generated from Service project for store backend communication
  • SharedSchema: Common data models shared across applications

Base Libraries

  • BaseApp.ViewModels: Shared MVVM framework and base classes
  • BaseApp.BlazorUI: Common UI components and utilities

Store-Specific Dependencies

  • StoreSchema: Store-specific data models and DTOs
  • StoreModule: Backend business logic for store operations

Development Workflow

Building

cd StoreApp
dotnet build StoreApp.sln

Running Web Version

cd WASMApp
dotnet run
# Accessible at /store/ path

Running MAUI Version

cd MAUIApp
dotnet build -f net9.0-windows10.0.19041.0

Clean Build

.\DeleteObjAndBin.ps1

Architectural Strengths

  1. Store-Focused Design: Optimized for store employee workflows and pet management
  2. Shared Architecture: Leverages same proven architecture as AdminApp
  3. Code Reuse: Shared UI components across web and mobile platforms
  4. Clean Separation: Clear boundaries between store UI, business logic, and API layers
  5. Real-Time Operations: Reactive UI for live inventory updates
  6. Multi-Platform Support: Consistent experience across web and mobile devices
  7. Tenant Isolation: Secure multi-store operations with proper data isolation
  8. Scalable Design: Can support multiple stores and high transaction volumes

Integration with MagicPets Ecosystem

StoreApp is part of the larger MagicPets ecosystem:

  • Consumes: StoreApi from Service project
  • Shares: BaseAppLib components with other applications
  • Coordinates: With ConsumerApp for customer-facing operations
  • Reports: To AdminApp for administrative oversight