@jwikman/bc-code-intelligence-mcp 1.5.7-dev.1

package/embedded-knowledge/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to Business Central Knowledge Base
+
+## Overview
+This repository contains pure knowledge content for Business Central best practices. All content is markdown with YAML frontmatter.
+
+## Content Standards
+
+### File Structure
+Each knowledge topic follows this structure:
+```markdown
+---
+title: "Topic Title"
+domain: "performance"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["sift", "optimization", "database"]
+related_topics: ["topic-id-1", "topic-id-2"]
+---
+
+# Topic Title
+
+Content here following established patterns...
+```
+
+### Quality Requirements
+- **Atomic Focus**: One concept per file
+- **BC Version Compatibility**: Always specify version ranges
+- **Complete Frontmatter**: All required YAML fields present
+- **Cross-References**: Link to related topics where appropriate
+- **Consistent Formatting**: Follow existing markdown patterns
+
+## Submission Process
+1. Fork the repository
+2. Create content following established patterns in appropriate domain directory
+3. Ensure YAML frontmatter is complete and valid
+4. Test that internal links work correctly
+5. Submit pull request with clear description of the knowledge added/updated
+
+## Content Validation
+Pull requests are automatically validated for:
+- YAML frontmatter completeness
+- BC version compatibility format
+- Internal link integrity
+- Proper domain/directory placement
+- Markdown formatting consistency
+
+## Domain Organization
+Place content in appropriate domain directories:
+- `domains/performance/` - Performance optimization
+- `domains/api-design/` - REST/OData patterns
+- `domains/security/` - Authentication/authorization
+- `domains/data-architecture/` - Table design
+- [See full domain list in repository structure]
+
+## Getting Help
+- Review existing topics for patterns
+- Check AGENTS.md for AI assistant guidance
+- Open issues for questions about content organization

package/embedded-knowledge/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Business Central Knowledge Base
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/embedded-knowledge/README.md

@@ -0,0 +1,32 @@
+# BC Code Intelligence Knowledge Base
+
+Pure knowledge content repository for Business Central best practices, methodologies, and domain expertise.
+
+## Structure
+- `/domains/` - 24 BC domains with 87+ atomic knowledge topics
+- `/methodologies/` - AI workflow frameworks for systematic optimization
+- `/specialists/` - 14 AI persona definitions for focused expertise
+- `/prompts/` - Strategic prompts for common BC scenarios
+
+## Specialists
+Complete roster of 14 BC development specialists:
+- **Alex Architect** - Strategic Planning & Architecture
+- **Casey Copilot** - AI-Enhanced Development Coach  
+- **Dean Debug** - Performance & Troubleshooting
+- **Eva Errors** - Error Handling & Exception Management
+- **Jordan Bridge** - Systems Connection & Event-Driven Design
+- **Logan Legacy** - Legacy Code & Version Migration
+- **Maya Mentor** - Learning & Skill Development
+- **Morgan Market** - AppSource & ISV Business Expert
+- **Quinn Tester** - Quality Validation & Test Design
+- **Roger Reviewer** - Code Quality & Review Standards
+- **Sam Coder** - Efficient Implementation Expert
+- **Seth Security** - Security & Permission Management
+- **Taylor Docs** - Documentation & Knowledge Management
+- **Uma UX** - User Experience & Interface Design
+
+## Usage
+This repository is consumed by the BC Code Intelligence MCP server via git submodule. Content is pure markdown with YAML frontmatter.
+
+## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md) for content standards and submission process.

package/embedded-knowledge/domains/alex-architect/api-delegate-operation-pattern.md

@@ -0,0 +1,90 @@
+---
+title: "API Delegate Operation Pattern"
+domain: "alex-architect"
+difficulty: "advanced"
+bc_versions: "14+"
+tags: ["api-delegates", "operation-delegation", "api-patterns", "extensibility"]
+prerequisites: ["api-basics", "interface-implementation", "event-handling"]
+samples: "samples/api-delegate-operation.md"
+related_topics: ["api-interface-design-patterns", "event-bridge-pattern-al"]
+---
+
+# API Delegate Operation Pattern
+
+## Overview
+
+The API Delegate Operation Pattern enables flexible API architectures by delegating specific operations to external handlers while maintaining consistent API contracts. This pattern is essential for building extensible APIs that can be enhanced by different modules without modifying core API logic.
+
+**Key Benefit**: Provides extensibility points in APIs while maintaining backward compatibility and clear separation of concerns.
+
+## Strategic Framework
+
+### Delegation Architecture
+Design APIs with explicit delegation points where external modules can register operation handlers, enabling customization without API modification.
+
+### Contract Preservation
+Maintain consistent API contracts while allowing internal operation logic to be delegated to specialized handlers based on context or configuration.
+
+### Dynamic Handler Selection
+Implement runtime handler selection mechanisms that choose appropriate delegates based on operation parameters, user context, or system configuration.
+
+## Core Implementation Patterns
+
+### Operation Delegate Interface
+Define clear interfaces for operation delegates that specify input parameters, expected outputs, and error handling contracts.
+
+### Delegate Registry Pattern
+Implement registration systems where modules can register their operation delegates, enabling discovery and selection at runtime.
+
+### Chain of Responsibility Integration
+Combine delegation with chain of responsibility patterns to enable multiple delegates to process operations in sequence.
+
+## Advanced Delegation Strategies
+
+### Contextual Delegation
+Use operation context (user, company, feature flags) to determine which delegate should handle specific operations.
+
+### Fallback Delegate Chains
+Implement fallback mechanisms where multiple delegates can be attempted if primary delegates fail or are unavailable.
+
+### Composite Operation Delegation
+Design delegates that can compose multiple sub-operations, enabling complex operation workflows through delegation.
+
+## Performance Considerations
+
+### Delegate Caching
+Cache delegate instances and registration information to minimize lookup overhead during high-frequency API operations.
+
+### Lazy Delegate Loading
+Implement lazy loading patterns for delegates to avoid unnecessary initialization overhead for unused operation paths.
+
+### Operation Profiling
+Monitor delegate operation performance to identify bottlenecks and optimize critical delegation paths.
+
+## Best Practices
+
+### Design Principles
+- Define clear delegate contracts with explicit input/output specifications
+- Implement robust error handling for delegate failures
+- Use dependency injection for delegate registration and discovery
+- Document delegation points and available extension mechanisms
+
+### Security Considerations
+- Validate delegate operations for security compliance
+- Implement authorization checks for delegate registration
+- Ensure delegate operations respect user permissions and data access rules
+
+## Common Pitfalls
+
+### Over-Delegation
+Avoid creating too many delegation points that make API behavior unpredictable or difficult to debug.
+
+### Delegate Coupling
+Prevent tight coupling between API logic and specific delegate implementations that reduces flexibility.
+
+### Performance Overhead
+Be mindful of delegation overhead in performance-critical scenarios where direct operation execution might be more appropriate.
+
+*Complete delegation implementation: samples/api-delegate-operation.md*
+*API design patterns: api-interface-design-patterns.md*
+*Event-driven delegation: event-bridge-pattern-al.md*

package/embedded-knowledge/domains/alex-architect/api-fieldset-registration-pattern.md

@@ -0,0 +1,113 @@
+---
+title: "API Fieldset Registration Pattern"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["api-fieldsets", "field-registration", "api-extensibility", "metadata-driven"]
+prerequisites: ["api-basics", "fieldset-concepts", "registration-patterns"]
+samples: "samples/api-fieldset-registration.md"
+related_topics: ["api-interface-design-patterns", "api-delegate-operation-pattern"]
+---
+
+# API Fieldset Registration Pattern
+
+## Overview
+
+The API Fieldset Registration Pattern enables dynamic field management in APIs by allowing modules to register field definitions that can be included in API responses. This pattern supports extensible APIs where different modules can contribute fields without modifying core API logic.
+
+**Key Benefit**: Enables flexible, extensible APIs where field availability can be determined dynamically based on installed modules and user permissions.
+
+## Strategic Framework
+
+### Dynamic Field Discovery
+Implement registration mechanisms where modules can register field definitions that become available for API consumption based on runtime conditions.
+
+### Metadata-Driven Selection
+Use metadata to describe field characteristics, enabling intelligent field selection based on client requirements and system capabilities.
+
+### Permission-Aware Fields
+Integrate field registration with permission systems to ensure only authorized fields are exposed through API responses.
+
+## Core Registration Patterns
+
+### Module-Based Registration
+Enable modules to register their field contributions during initialization, allowing for modular field extension without core API changes.
+
+### Conditional Field Registration
+Implement registration logic that considers system configuration, feature flags, and user context to determine field availability.
+
+### Hierarchical Field Organization
+Organize registered fields in hierarchical structures that support grouping, categorization, and efficient lookup operations.
+
+## Implementation Strategies
+
+### Registry Architecture
+Design field registries that support efficient lookup, validation, and metadata management for dynamic field selection.
+
+### Field Metadata Management
+Implement comprehensive field metadata including data types, validation rules, permission requirements, and display characteristics.
+
+### Selection Optimization
+Optimize field selection algorithms to minimize performance impact when processing large numbers of registered fields.
+
+## Advanced Registration Features
+
+### Field Dependency Management
+Implement dependency tracking between fields to ensure required fields are included when dependent fields are selected.
+
+### Field Transformation Pipelines
+Design transformation pipelines that can modify field values during API response generation based on registration metadata.
+
+### Caching Strategies
+Implement caching for field registration data to improve API response performance for frequently accessed field sets.
+
+## Performance Considerations
+
+### Registration Overhead
+Minimize registration overhead through efficient storage and indexing of field metadata and registration information.
+
+### Selection Performance
+Optimize field selection algorithms to support high-frequency API operations without significant performance degradation.
+
+### Memory Management
+Implement efficient memory management for field registration data to prevent memory leaks and excessive resource usage.
+
+## Security and Validation
+
+### Permission Integration
+- Integrate field registration with permission systems
+- Validate user authorization for specific field access
+- Implement field-level security policies
+- Support dynamic permission evaluation
+
+### Data Validation
+- Validate registered field definitions for correctness
+- Implement runtime validation of field values
+- Support custom validation rules per registered field
+- Ensure data type consistency across registrations
+
+## Best Practices
+
+### Registration Design
+- Use strongly-typed field registration interfaces
+- Implement clear naming conventions for registered fields
+- Provide comprehensive metadata for each registered field
+- Support registration validation and error reporting
+
+### API Integration
+- Design consistent field selection patterns across API endpoints
+- Implement clear documentation for available fields
+- Support field discovery mechanisms for API consumers
+- Provide examples of field selection usage
+
+## Common Pitfalls
+
+### Over-Registration
+Avoid registering too many fields that can overwhelm API consumers and impact performance through excessive selection overhead.
+
+### Inconsistent Metadata
+Prevent inconsistent field metadata that can lead to unpredictable API behavior and difficult debugging scenarios.
+
+*Complete fieldset registration examples: samples/api-fieldset-registration.md*
+*API interface patterns: api-interface-design-patterns.md*
+*Dynamic API patterns: api-delegate-operation-pattern.md*

package/embedded-knowledge/domains/alex-architect/api-interface-design-patterns.md

@@ -0,0 +1,101 @@
+---
+title: "API Interface Design Patterns"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["api-interfaces", "contract-design", "api-patterns", "interface-segregation"]
+prerequisites: ["interface-basics", "api-fundamentals", "contract-design"]
+samples: "samples/api-interface-design.md"
+related_topics: ["api-delegate-operation-pattern", "api-fieldset-registration-pattern"]
+---
+
+# API Interface Design Patterns
+
+## Overview
+
+API Interface Design Patterns provide proven approaches for creating maintainable, extensible, and user-friendly API contracts. These patterns ensure APIs remain stable while supporting evolution and provide clear contracts for consumers.
+
+**Key Benefit**: Creates predictable, maintainable API contracts that support long-term evolution without breaking existing consumers.
+
+## Core Design Principles
+
+### Interface Segregation
+Design focused interfaces that serve specific purposes rather than monolithic interfaces that attempt to handle all scenarios.
+
+### Contract Stability
+Maintain backward compatibility through careful interface evolution strategies and versioning approaches.
+
+### Consumer-Centric Design
+Design interfaces from the consumer perspective, optimizing for common usage patterns and developer experience.
+
+## Essential Interface Patterns
+
+### Command-Query Separation
+Separate interfaces for operations that modify state (commands) from those that retrieve data (queries), enabling clearer contracts and better optimization opportunities.
+
+### Fluent Interface Pattern
+Design method chaining interfaces that enable expressive, readable API usage while maintaining type safety and clear operation sequencing.
+
+### Builder Interface Pattern
+Implement builder-style interfaces for complex object construction scenarios where multiple optional parameters need to be specified.
+
+## Versioning and Evolution Strategies
+
+### Additive Interface Evolution
+Design interfaces to support evolution through additive changes that don't break existing consumers while enabling new functionality.
+
+### Interface Composition
+Use interface composition to build complex API contracts from smaller, focused interface components that can evolve independently.
+
+### Deprecation Patterns
+Implement clear deprecation strategies that provide migration paths for consumers while enabling interface evolution.
+
+## Advanced Interface Patterns
+
+### Contextual Interface Adaptation
+Design interfaces that adapt their behavior based on context (user permissions, feature flags, system configuration) while maintaining consistent contracts.
+
+### Generic Interface Patterns
+Use generic interfaces to provide type-safe operations across different data types while maintaining consistent operation patterns.
+
+### Callback Interface Integration
+Integrate callback interfaces for asynchronous operations and event handling while maintaining clear contract boundaries.
+
+## Implementation Guidelines
+
+### Parameter Design
+- Use strongly-typed parameters with clear naming conventions
+- Implement validation at interface boundaries
+- Provide clear documentation for parameter requirements and constraints
+- Consider parameter object patterns for complex method signatures
+
+### Return Value Patterns
+- Design consistent return value patterns across interface methods
+- Use result objects for operations that can fail with detailed error information
+- Implement null object patterns where appropriate to avoid null reference issues
+
+## Best Practices
+
+### Documentation Standards
+- Provide comprehensive interface documentation with examples
+- Document expected behaviors, side effects, and error conditions
+- Include performance characteristics and usage guidelines
+- Maintain versioning documentation for interface evolution
+
+### Error Handling Design
+- Design consistent error handling patterns across all interface methods
+- Use typed exceptions or result objects for error communication
+- Provide actionable error messages for consumers
+- Implement proper error recovery guidance
+
+## Common Pitfalls
+
+### Interface Bloat
+Avoid creating large interfaces that try to handle too many scenarios, making them difficult to implement and maintain.
+
+### Breaking Changes
+Prevent accidental breaking changes through careful interface evolution planning and comprehensive testing strategies.
+
+*Complete interface design examples: samples/api-interface-design.md*
+*Delegation patterns: api-delegate-operation-pattern.md*
+*Registration patterns: api-fieldset-registration-pattern.md*

package/embedded-knowledge/domains/alex-architect/api-page-development-patterns.md

@@ -0,0 +1,87 @@
+---
+title: "AL API Page Development Patterns"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["api", "pages", "odata", "integration", "architecture"]
+samples: "samples/api-page-implementation.md"
+type: "implementation-pattern"
+category: "api-development"
+pattern_type: "good"
+severity: "medium"
+impact_level: "high"
+improvement_suggestion: "Use API pages for structured external system integration"
+implementation_steps: ["design-api-structure", "implement-field-exposure", "optimize-performance"]
+validation_criteria: ["odata-compliance", "security-integration", "performance-optimization"]
+technical_areas: ["al-code", "integration"]
+---
+
+# AL API Page Development Patterns
+
+## Overview
+
+API pages in Business Central provide structured OData endpoints for external system integration. Unlike standard pages, API pages focus exclusively on data exchange with minimal UI considerations, requiring careful design for optimal performance and maintainability.
+
+**Key Decision**: API pages should expose logical business entities rather than raw table structures, providing stable integration contracts that abstract internal data organization.
+
+## Strategic Framework
+
+### API Page Design Philosophy
+- **Business Entity Focus**: Expose meaningful business concepts (Customer, Item, SalesOrder) rather than normalized table structures
+- **Contract Stability**: Maintain consistent field names and structures across BC versions to protect integration investments
+- **Performance Optimization**: Design for efficient data retrieval and modification patterns expected by consuming applications
+- **Security Integration**: Leverage BC's built-in authentication and authorization without exposing sensitive internal structures
+
+### Integration Architecture Patterns
+API pages serve as the primary integration layer between Business Central and external systems. They should provide complete business entity representations while maintaining clear separation between internal data models and external contracts.
+
+## Architecture Focus
+
+### Page Structure Design
+API pages require specific architectural considerations distinct from interactive pages. The PageType API designation enables OData endpoint generation with automatic JSON serialization and standardized query capabilities.
+
+### Field Exposure Strategy
+Expose fields that represent complete business entity state while avoiding internal implementation details. Include essential business identifiers, descriptive fields, and workflow status information that external systems need for business logic.
+
+### Relationship Management
+Design API pages to include related entity references through careful use of lookup fields and calculated fields. This enables consuming applications to navigate business relationships without requiring multiple API calls.
+
+### Version Compatibility
+Structure API pages to maintain backward compatibility as business requirements evolve. Use consistent naming conventions and avoid breaking changes to established field contracts.
+
+## Best Practices
+
+### Entity Modeling
+- **Complete Business Context**: Include all fields necessary for external systems to make business decisions
+- **Logical Grouping**: Group related information to minimize round-trips for common business scenarios
+- **Status Visibility**: Expose workflow states and business status fields that affect integration logic
+- **Audit Information**: Include creation dates, modification timestamps, and responsible user information
+
+### Performance Considerations
+- **Selective Field Loading**: Design pages to load only necessary fields for common query patterns
+- **Efficient Filtering**: Support standard OData filtering on key business fields like dates, status, and identifiers
+- **Batch Operation Support**: Enable bulk data operations where business processes require them
+- **Caching Awareness**: Structure responses to support effective caching strategies in consuming applications
+
+### Security Implementation
+- **Principle of Least Privilege**: Expose only fields that external systems legitimately need for business operations
+- **Sensitive Data Protection**: Exclude internal identifiers, system fields, and confidential business information
+- **Access Control Integration**: Leverage BC's permission system to control API access at field and record levels
+- **Audit Trail Maintenance**: Ensure API operations create appropriate audit records for compliance requirements
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Direct Table Exposure**: Exposing raw table structures without business context abstraction
+- **Internal Field Leakage**: Including system fields, internal identifiers, or implementation details in API contracts
+- **Incomplete Entity Representation**: Requiring multiple API calls to reconstruct basic business entity state
+- **Breaking Contract Changes**: Modifying existing field names or removing fields without proper versioning strategy
+
+### Common Design Mistakes
+- **Over-Normalization**: Creating APIs that mirror database structure rather than business entity logic
+- **Under-Documentation**: Failing to provide clear guidance on field usage and business meaning
+- **Security Oversights**: Exposing sensitive information or bypassing standard BC security mechanisms
+- **Performance Blindness**: Designing APIs without considering query patterns and data volume implications
+
+*Implementation examples: see samples/api-page-implementation.md*
+*Related patterns: facade-pattern-external-api.md, api-authentication-patterns.md*

package/embedded-knowledge/domains/alex-architect/complex-facade-patterns.md

@@ -0,0 +1,155 @@
+---
+title: "Complex Facade Patterns"
+domain: "alex-architect"
+difficulty: "advanced"
+bc_versions: "14+"
+tags: ["complex-facade", "enterprise-patterns", "multi-layer-facade", "facade-composition"]
+prerequisites: ["facade-pattern-al-implementation", "enterprise-architecture", "advanced-al"]
+samples: "samples/complex-facade-patterns.md"
+related_topics: ["facade-pattern-al-implementation", "enterprise-integration-patterns"]
+---
+
+# Complex Facade Patterns
+
+## Overview
+
+Complex Facade Patterns extend basic facade concepts to handle enterprise-scale scenarios involving multiple subsystems, cross-cutting concerns, and sophisticated business logic coordination. These patterns enable management of intricate system architectures while maintaining clean, manageable interfaces.
+
+**Key Benefit**: Enables management of complex enterprise systems through sophisticated facade architectures that maintain simplicity for consumers while handling intricate backend coordination.
+
+## Advanced Facade Architectures
+
+### Multi-Layer Facade Systems
+Design facade hierarchies where higher-level facades coordinate lower-level facades, enabling different abstraction levels for different consumer types.
+
+### Composite Facade Coordination
+Implement facade composition patterns where multiple specialized facades work together to provide comprehensive business capability interfaces.
+
+### Domain-Specific Facade Clusters
+Create facade clusters that serve specific business domains while maintaining coordination capabilities for cross-domain operations.
+
+## Enterprise Integration Patterns
+
+### Cross-System Facade Orchestration
+Design facades that coordinate operations across multiple Business Central environments, external systems, and cloud services.
+
+### Transaction-Spanning Facades
+Implement facades that manage distributed transactions and coordination across multiple systems while providing simple operation interfaces.
+
+### Event-Driven Facade Coordination
+Integrate complex facades with event-driven architectures to enable reactive coordination and loose coupling between facade layers.
+
+## Sophisticated Business Logic Patterns
+
+### Workflow Facade Integration
+Design facades that encapsulate complex workflow orchestration, managing state transitions, approvals, and business rule enforcement.
+
+### Policy-Driven Facade Behavior
+Implement facades that adapt their behavior based on business policies, user roles, and dynamic configuration without interface changes.
+
+### Context-Sensitive Facade Operations
+Create facades that provide different capabilities and behaviors based on execution context, user permissions, and system state.
+
+## Performance and Scalability Patterns
+
+### Caching-Enabled Facade Architecture
+- Implement multi-level caching within facade hierarchies
+- Design cache invalidation strategies for complex data dependencies
+- Support distributed caching for multi-instance scenarios
+- Optimize cache performance for high-frequency facade operations
+
+### Asynchronous Facade Operations
+- Design asynchronous facade patterns for long-running operations
+- Implement callback and notification mechanisms for async completion
+- Support progress tracking and cancellation for complex operations
+- Enable parallel execution of independent facade operations
+
+## Advanced Error Handling
+
+### Cascade Error Management
+Implement sophisticated error handling that can manage failures across multiple facade layers and subsystem components.
+
+### Recovery and Compensation
+Design compensation patterns that can recover from partial failures in complex operations spanning multiple systems.
+
+### Circuit Breaker Integration
+Integrate circuit breaker patterns within facades to prevent cascade failures and enable graceful degradation.
+
+## Security and Compliance Patterns
+
+### Multi-Tenant Facade Security
+Design facades that handle multi-tenant security concerns while providing unified interfaces across tenant boundaries.
+
+### Compliance-Aware Operations
+Implement facades that automatically handle compliance requirements such as audit logging, data retention, and privacy regulations.
+
+### Permission-Based Facade Adaptation
+Create facades that dynamically adapt their available operations based on user permissions and security policies.
+
+## Monitoring and Diagnostics
+
+### Facade Performance Analytics
+Implement comprehensive performance monitoring across facade hierarchies to identify bottlenecks and optimization opportunities.
+
+### Operation Tracing
+Design distributed tracing capabilities that can track operations across multiple facade layers and subsystem components.
+
+### Health Monitoring
+Create health monitoring systems that can assess the status of complex facade architectures and provide early warning of issues.
+
+## Integration Strategies
+
+### API Gateway Facade Patterns
+Design facades that serve as API gateways, providing external access to complex internal capabilities with appropriate security and rate limiting.
+
+### Microservice Facade Coordination
+Implement facades that coordinate microservice interactions while hiding service discovery, load balancing, and failure handling.
+
+### Legacy System Integration
+Create facades that modernize access to legacy systems while maintaining compatibility and enabling gradual migration strategies.
+
+## Testing Complex Facades
+
+### Multi-Layer Testing Strategies
+- Implement testing strategies that validate facade behavior at multiple abstraction levels
+- Design integration testing that covers complete facade interaction scenarios
+- Support performance testing under realistic load conditions
+- Enable chaos engineering testing for resilience validation
+
+### Mock and Simulation Patterns
+- Create sophisticated mocking strategies for complex facade dependencies
+- Design simulation capabilities for testing facade behavior under various conditions
+- Support A/B testing for facade behavior changes
+- Enable testing of failure scenarios and recovery patterns
+
+## Best Practices
+
+### Architectural Principles
+- Maintain clear separation of concerns across facade layers
+- Design for both horizontal and vertical scaling requirements
+- Implement comprehensive monitoring and observability
+- Plan for facade evolution and migration strategies
+
+### Operational Excellence
+- Provide detailed documentation for complex facade architectures
+- Implement automated testing and deployment pipelines
+- Support configuration management for complex facade behaviors
+- Maintain clear operational procedures for complex facade management
+
+## Common Pitfalls
+
+### Over-Engineering
+Avoid creating unnecessarily complex facade architectures that become harder to maintain than the systems they're meant to simplify.
+
+### Performance Overhead
+Prevent facade layers from introducing significant performance overhead that negates the benefits of system simplification.
+
+### Tight Coupling
+Avoid creating tight coupling between facade layers that reduces system flexibility and makes changes difficult.
+
+### Monitoring Gaps
+Ensure comprehensive monitoring coverage across all facade layers to prevent issues from going undetected in complex architectures.
+
+*Complete complex facade examples: samples/complex-facade-patterns.md*
+*Basic facade patterns: facade-pattern-al-implementation.md*
+*Enterprise integration: enterprise-integration-patterns.md*