@khester/create-dynamics-app 2.0.0 → 2.2.0

package/templates/react-custom-page/docs/ARCHITECTURE_OVERVIEW.md

@@ -1,506 +0,0 @@
-# Architecture Overview - Dynamics 365 Template
-
-## Executive Summary
-
-The Enhanced Dynamics 365 Template provides a comprehensive, enterprise-grade foundation for
-building sophisticated React applications that integrate seamlessly with Microsoft Dynamics 365.
-Built with TypeScript, modern React patterns, and Fluent UI v8, this template delivers
-production-ready code with advanced features including entity models, service layer abstraction,
-comprehensive logging, and intelligent environment detection.
-
-## High-Level Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    Dynamics 365 Template                        │
-├─────────────────────────────────────────────────────────────────┤
-│  Presentation Layer (React Components)                          │
-│  ├── Management Components (Account/Contact/Opportunity)        │
-│  ├── Form Components (Validation & Submission)                  │
-│  ├── PCF Wrappers (Custom Control Integration)                  │
-│  └── UI Components (Fluent UI v8)                              │
-├─────────────────────────────────────────────────────────────────┤
-│  Context & Providers                                           │
-│  ├── DynamicsProvider (API Service Context)                    │
-│  ├── LoggingProvider (Centralized Logging)                     │
-│  └── React Context API (State Management)                      │
-├─────────────────────────────────────────────────────────────────┤
-│  Business Logic Layer                                          │
-│  ├── Entity Models (Account, Contact, BaseEntity)              │
-│  ├── Constants (Field Definitions & Metadata)                  │
-│  ├── Validation (Client-side & Business Rules)                 │
-│  └── Workflows (Multi-entity Business Processes)               │
-├─────────────────────────────────────────────────────────────────┤
-│  Service Layer                                                 │
-│  ├── ServiceFactory (Environment Detection)                    │
-│  ├── XrmApiService (Production D365 Integration)               │
-│  ├── MockApiService (Development & Testing)                    │
-│  └── IApiService (Common Interface)                            │
-├─────────────────────────────────────────────────────────────────┤
-│  Infrastructure Layer                                          │
-│  ├── Logger (Structured Logging System)                        │
-│  ├── Error Handling (Layered Error Management)                 │
-│  ├── Build System (Custom Webpack Configuration)               │
-│  └── Deployment (Web Resources, PCF, Custom Pages)             │
-└─────────────────────────────────────────────────────────────────┘
-                                   │
-                         ┌─────────▼─────────┐
-                         │   Dynamics 365    │
-                         │                   │
-                         │  ├── Web API      │
-                         │  ├── Xrm Object   │
-                         │  ├── FetchXML     │
-                         │  └── Custom APIs  │
-                         └───────────────────┘
-```
-
-## Core Architectural Patterns
-
-### 1. Entity Model Pattern
-
-**Purpose**: Provide a consistent, type-safe interface for Dynamics 365 entity operations with
-built-in validation and logging.
-
-**Implementation**:
-
-```typescript
-export class Account extends BaseEntity implements IAccount {
-  // Static CRUD operations
-  public static async create(apiService: IApiService, account: Account): Promise<Account>;
-  public static async retrieveByName(apiService: IApiService, name: string): Promise<Account[]>;
-  public static async update(
-    apiService: IApiService,
-    id: string,
-    account: Account
-  ): Promise<Account>;
-  public static async delete(apiService: IApiService, id: string): Promise<void>;
-
-  // Instance validation
-  public validate(): boolean;
-}
-```
-
-**Benefits**:
-
-- Consistent API across all entities
-- Built-in validation and error handling
-- Comprehensive logging for all operations
-- Type safety with TypeScript
-- Reusable patterns for custom entities
-
-### 2. Service Factory Pattern
-
-**Purpose**: Automatically detect the runtime environment and provide the appropriate API service
-implementation.
-
-**Implementation**:
-
-```typescript
-export class ServiceFactory {
-  public static createApiService(Xrm?: any): IApiService {
-    if (this.isMockEnvironment) {
-      return new MockApiService();
-    }
-    return new XrmApiService(Xrm);
-  }
-
-  public static get isMockEnvironment(): boolean {
-    return window.location.hostname === 'localhost';
-  }
-}
-```
-
-**Benefits**:
-
-- Seamless development-to-production workflow
-- No code changes required between environments
-- Automatic fallback mechanisms
-- Easy testing with mock services
-
-### 3. Provider Pattern for Context Management
-
-**Purpose**: Manage API services and logging context throughout the React component tree.
-
-**Implementation**:
-
-```typescript
-export const DynamicsProvider: React.FC<DynamicsProviderProps> = ({
-  children,
-  customApiService
-}) => {
-  const apiService = useMemo(() => {
-    return customApiService || ServiceFactory.createApiService();
-  }, [customApiService]);
-
-  return (
-    <DynamicsContext.Provider value={{ apiService, environmentType, isEnvironmentMock }}>
-      {children}
-    </DynamicsContext.Provider>
-  );
-};
-```
-
-**Benefits**:
-
-- Clean dependency injection
-- Easy testing with custom services
-- Centralized configuration
-- Type-safe context consumption
-
-### 4. Layered Error Handling
-
-**Purpose**: Provide comprehensive error management from API calls through user interface feedback.
-
-**Implementation**:
-
-```typescript
-// Layer 1: API Service Level
-class XrmApiService {
-  async createRecord(entityName: string, record: any): Promise<any> {
-    try {
-      return await this.xrm.WebApi.createRecord(entityName, record);
-    } catch (error) {
-      Logger.error(`API operation failed`, 'XrmApiService.createRecord', error);
-      throw new Error(`Unable to create ${entityName}: ${error}`);
-    }
-  }
-}
-
-// Layer 2: Entity Model Level
-class Account {
-  public static async create(apiService: IApiService, account: Account): Promise<Account> {
-    try {
-      account.validate(); // Business logic validation
-      return await this.createEntity(apiService, account, AccountConstants.EntityCollectionName);
-    } catch (error) {
-      Logger.error('Account creation failed', 'Account.create', error);
-      throw error; // Re-throw for component handling
-    }
-  }
-}
-
-// Layer 3: Component Level
-const AccountForm: React.FC = () => {
-  const [error, setError] = useState<string>('');
-
-  const handleSubmit = async () => {
-    try {
-      await Account.create(apiService, formData);
-      onSuccess();
-    } catch (error) {
-      setError(getUserFriendlyErrorMessage(error));
-      Logger.error('Form submission failed', 'AccountForm.handleSubmit', error);
-    }
-  };
-};
-```
-
-### 5. Comprehensive Logging Architecture
-
-**Purpose**: Provide structured, queryable logging for debugging, monitoring, and business
-intelligence.
-
-**Implementation**:
-
-```typescript
-export class Logger {
-  // User action tracking
-  static userAction(action: string, data: any, context: string): void;
-
-  // API operation logging
-  static apiOperation(operation: string, entity: string, data: any, context: string): void;
-
-  // Performance monitoring
-  static timing(operation: string, startTime: number, context: string): void;
-
-  // Business rule validation
-  static validation(entity: string, errors: string[], context: string): void;
-
-  // FetchXML query logging
-  static fetchXml(query: string, context: string): void;
-}
-```
-
-**Log Categories**:
-
-- **User Actions**: Button clicks, form submissions, navigation
-- **API Operations**: CRUD operations, custom API calls
-- **Performance**: Operation timing, slow queries
-- **Validation**: Business rule enforcement, data validation
-- **Errors**: Exception details with context
-- **Debug**: Development troubleshooting information
-
-## Technology Stack
-
-### Frontend Framework
-
-- **React 18**: Modern component architecture with hooks
-- **TypeScript**: Full type safety and IntelliSense support
-- **Fluent UI v8**: Microsoft's design system for consistency
-
-### Build & Development
-
-- **Webpack 5**: Custom configuration optimized for D365
-- **ESLint**: Code quality and consistency enforcement
-- **CSS Modules**: Scoped styling to prevent conflicts
-
-### Dynamics 365 Integration
-
-- **Xrm.WebApi**: Direct integration with D365 Web API
-- **FetchXML**: Optimized queries for data retrieval
-- **PCF Framework**: Custom control development support
-
-## Deployment Architecture
-
-### Web Resources Deployment
-
-```
-Dynamics 365 Environment
-├── Web Resources
-│   ├── Script (JScript): /new_scripts/main.js (726 KB)
-│   ├── Style Sheet (CSS): /new_styles/app.css
-│   └── Web Page (HTML): /new_pages/index.html
-├── Security Roles
-│   ├── Read permissions for entities
-│   ├── Write permissions for data operations
-│   └── Web resource access permissions
-└── Custom Pages/Forms
-    ├── Account Management Page
-    ├── Contact Management Page
-    └── Multi-Entity Dashboard
-```
-
-### PCF Control Deployment
-
-```
-PCF Solution Package
-├── Control Manifest (ControlManifest.Input.xml)
-├── TypeScript Sources (/src/)
-├── React Components (/components/)
-├── Entity Models (/models/)
-├── Build Output (/out/controls/)
-└── Solution Package (.zip)
-```
-
-### Custom Pages Deployment
-
-```
-Model-Driven App
-├── Custom Pages
-│   ├── Account Management (accountmanagement.html)
-│   ├── Contact Dashboard (contactdashboard.html)
-│   └── Opportunity Pipeline (opportunitypipeline.html)
-├── Navigation
-│   ├── Sitemap entries
-│   └── Custom navigation items
-└── Security
-    ├── Security roles assignment
-    └── Field-level security
-```
-
-## Data Flow Architecture
-
-### 1. User Interaction Flow
-
-```
-User Action → Component Event Handler → Entity Model Method → API Service → D365 Web API
-                    ↓                          ↓                  ↓             ↓
-              State Update ← Component Update ← Response Handler ← HTTP Response
-```
-
-### 2. Logging Flow
-
-```
-Operation → Logger Method → Log Entry Creation → Console Output
-    ↓              ↓                ↓                 ↓
-Context Data → Structured → Local Storage → Debug Panel
-```
-
-### 3. Error Handling Flow
-
-```
-API Error → Service Layer → Entity Model → Component Handler → User Feedback
-    ↓           ↓             ↓              ↓                ↓
-Logger → Structured Log → Context Data → Error State → UI Display
-```
-
-## Security Architecture
-
-### Authentication & Authorization
-
-```typescript
-// Permission checking before operations
-const checkPermissions = async (operation: string, entityName: string): Promise<boolean> => {
-  try {
-    const userPrivileges = await Xrm.Utility.getGlobalContext().getUserPrivileges();
-    return userPrivileges.some(
-      (privilege) => privilege.privilegeName === `prv${operation}${entityName}`
-    );
-  } catch {
-    return false; // Fail secure
-  }
-};
-```
-
-### Input Validation & Sanitization
-
-```typescript
-// Multi-layer validation
-class BaseEntity {
-  // XSS prevention
-  protected static escapeXml(value: string): string;
-
-  // Input length enforcement
-  protected static validateInput(input: string, maxLength: number): string;
-
-  // SQL injection prevention in FetchXML
-  protected static buildFetchXml(entityName: string, attributes: string[], filter?: string): string;
-}
-```
-
-### Data Privacy
-
-- **Field-level security**: Respect D365 security model
-- **Audit logging**: Track all data access and modifications
-- **Encryption**: Leverage D365's built-in encryption
-- **Access control**: Role-based permissions enforcement
-
-## Performance Architecture
-
-### Bundle Optimization
-
-- **Production bundle**: 726 KB (optimized)
-- **Development bundle**: 3.95 MB (with debugging)
-- **Code splitting**: Automatic vendor chunk separation
-- **Tree shaking**: Eliminate unused code
-
-### Runtime Performance
-
-```typescript
-// Efficient data loading
-const loadAccountsOptimized = async () => {
-  // Only load required fields
-  const fetchXml = Account.buildFetchXml(
-    'account',
-    ['accountid', 'name', 'emailaddress1'], // Minimal field set
-    filter,
-    { attribute: 'createdon', descending: true }
-  );
-
-  // Implement pagination
-  return await Account.retrieveEntitiesByFilter(apiService, 'accounts', fetchXml, Account);
-};
-
-// React optimization
-const AccountManagement = React.memo(() => {
-  // Memoized calculations
-  const filteredAccounts = useMemo(
-    () => accounts.filter((account) => account.name?.includes(searchText)),
-    [accounts, searchText]
-  );
-
-  // Callback memoization
-  const handleItemInvoked = useCallback((item: Account) => {
-    setSelectedAccount(item);
-  }, []);
-});
-```
-
-### Caching Strategy
-
-- **Session storage**: API service instances
-- **Memory caching**: Component state optimization
-- **Browser caching**: Static asset optimization
-- **D365 caching**: Leverage platform caching
-
-## Scalability Considerations
-
-### Horizontal Scaling
-
-- **Modular architecture**: Easy to split into micro-frontends
-- **Service abstraction**: Support for multiple D365 environments
-- **Component isolation**: Independent development and deployment
-
-### Vertical Scaling
-
-- **Lazy loading**: Load components on demand
-- **Code splitting**: Reduce initial bundle size
-- **Efficient queries**: Optimized FetchXML generation
-- **Memory management**: Proper cleanup and garbage collection
-
-## Monitoring & Observability
-
-### Application Monitoring
-
-```typescript
-// Performance monitoring
-const performanceObserver = new PerformanceObserver((list) => {
-  for (const entry of list.getEntries()) {
-    if (entry.duration > 1000) {
-      Logger.performance('Slow operation detected', {
-        name: entry.name,
-        duration: entry.duration,
-      });
-    }
-  }
-});
-
-// Error tracking
-window.addEventListener('error', (event) => {
-  Logger.error('Unhandled error', 'GlobalErrorHandler', {
-    message: event.error?.message,
-    stack: event.error?.stack,
-    filename: event.filename,
-    lineno: event.lineno,
-  });
-});
-```
-
-### Business Intelligence
-
-- **User action tracking**: All user interactions logged
-- **Performance metrics**: Operation timing and success rates
-- **Error analytics**: Categorized error patterns
-- **Usage patterns**: Feature adoption and user workflows
-
-## Future Architecture Considerations
-
-### Microservices Ready
-
-- **Service abstraction**: Easy to split into separate services
-- **API gateway**: Centralized API management
-- **Event-driven**: Support for event sourcing patterns
-
-### Cloud Native
-
-- **Container support**: Docker-ready build process
-- **CI/CD integration**: Automated testing and deployment
-- **Monitoring**: Application Insights integration
-- **Scaling**: Kubernetes deployment support
-
-### Advanced Features
-
-- **Real-time updates**: SignalR integration capability
-- **Offline support**: Progressive Web App features
-- **Mobile optimization**: Responsive design and touch support
-- **AI integration**: Power Platform AI Builder support
-
-## Conclusion
-
-The Enhanced Dynamics 365 Template provides a robust, scalable, and maintainable foundation for
-enterprise-grade Dynamics 365 applications. Its layered architecture, comprehensive error handling,
-and modern development practices ensure that applications built with this template can grow and
-evolve with changing business requirements while maintaining high standards of quality, performance,
-and user experience.
-
-The template's design philosophy emphasizes:
-
-- **Developer Experience**: Modern tooling and clear patterns
-- **Type Safety**: Full TypeScript support throughout
-- **Maintainability**: Clean architecture and comprehensive documentation
-- **Performance**: Optimized builds and efficient runtime execution
-- **Security**: Multiple layers of validation and authorization
-- **Observability**: Comprehensive logging and monitoring capabilities
-
-This architecture serves as both a practical implementation and a reference for building
-sophisticated Dynamics 365 integrations that meet enterprise requirements.