🎯 Architecture Patterns & Core Concepts¶

Welcome to architecture patterns! This section explains the patterns and principles that Neuroglia is built upon. Each pattern is explained for beginners - you don't need prior knowledge.

📖 Note: Pattern documentation includes beginner-friendly What & Why sections showing problems and solutions, Common Mistakes with anti-patterns, and When NOT to Use guidance.

🎯 Why These Patterns?¶

Neuroglia enforces specific architectural patterns because they solve real problems in software development:

• Maintainability: Code that's easy to change as requirements evolve
• Testability: Components that can be tested in isolation
• Scalability: Architecture that grows with your application
• Clarity: Clear separation of concerns and responsibilities

� Quick Start Learning Path¶

New to these patterns? Follow this recommended path:

1. Foundation: Clean Architecture - Organizing code in layers
2. Dependencies: Dependency Injection - Managing components
3. Domain Logic: Domain-Driven Design - Modeling business rules
4. Application Layer: CQRS - Separating reads from writes
5. Integration: Event-Driven Architecture - Reacting to events
6. Data Access: Repository - Abstracting persistence

Already familiar? Jump to any pattern for Neuroglia-specific implementation details.

💡 What Each Guide Includes¶

• ❌ The Problem: What happens without this pattern
• ✅ The Solution: How the pattern solves it
• 🔧 In Neuroglia: Framework implementation details
• 🧪 Testing: How to test code using this pattern
• ⚠️ Common Mistakes: Pitfalls to avoid
• 🚫 When NOT to Use: Scenarios where simpler approaches work better

🏗️ Architectural Approaches: A Comparative Introduction¶

Before diving into specific patterns, it's essential to understand the different architectural philosophies that drive modern system design. The Neuroglia framework draws from multiple architectural approaches, each with distinct strengths and use cases.

🎯 Core Philosophy Comparison¶

Domain-Driven Design (DDD) and Declarative Resource-Oriented Architecture represent two powerful but different approaches to managing complex system states:

• DDD: Models systems around business domains, focusing on behavior and state transitions
• Declarative Architecture: Defines desired end states and uses automated processes to achieve them

🔄 Architectural Patterns Overview¶

🎨 Practical Analogies¶

• DDD is like giving a chef specific recipe instructions: "Add 20g of cheese to the pizza" - explicit commands executed immediately
• Declarative Architecture is like giving the chef a photograph of the final pizza: "Make it look like this" - continuous checking and adjustment until the goal is achieved

📡 Event-Driven Architecture: The Foundation¶

Event-Driven Architecture (EDA) serves as the postal service 📬 of your system - a foundational pattern enabling reactive communication without tight coupling between components.

🏛️ EDA in Domain-Driven Design¶

In DDD, EDA handles side effects and communication between different business domains (Bounded Contexts):

• Purpose: Reacting to significant business moments
• Mechanism: AggregateRoot publishes DomainEvents (e.g., OrderPaid, PizzaBaked)
• Benefit: Highly decoupled systems where services don't need direct knowledge of each other

Example: Orders service publishes OrderPaid → Kitchen service receives event and starts pizza preparation

🌐 EDA in Declarative Architecture¶

In declarative systems, EDA powers the reconciliation loop:

• Purpose: Reacting to changes in configuration or state
• Mechanism: Watcher monitors resources → generates events → Controller consumes events and reconciles state
• Benefit: Automated state management with continuous convergence toward desired state

Example: YAML file creates Deployment → API server generates "resource created" event → Deployment controller creates required pods

🔄 Integration Summary¶

🎯 Choosing Your Approach¶

Both patterns leverage EDA for reactive, decoupled systems but differ in event nature and granularity:

• DDD: Focus on high-level business events with rich domain behavior
• Declarative: Focus on low-level resource state changes with automated convergence

The Neuroglia framework provides implementations for both approaches, allowing you to choose the right pattern for each part of your system.

�🏛️ Pattern Overview¶

🍕 Mario's Pizzeria: Unified Example¶

All patterns use Mario's Pizzeria as a consistent domain example, showing how patterns work together in a real-world system:

graph TB
    subgraph "🏗️ Clean Architecture Layers"
        API[🌐 API Layer<br/>Controllers & DTOs]
        APP[💼 Application Layer<br/>Commands & Queries]
        DOM[🏛️ Domain Layer<br/>Entities & Events]
        INT[🔌 Integration Layer<br/>Repositories & Services]
    end

    subgraph "📡 CQRS Implementation"
        CMD[Commands<br/>PlaceOrder, StartCooking]
        QRY[Queries<br/>GetOrder, GetMenu]
    end

    subgraph "🔄 Event-Driven Flow"
        EVT[Domain Events<br/>OrderPlaced, OrderReady]
        HDL[Event Handlers<br/>Kitchen, Notifications]
    end

    subgraph "💾 Data Access"
        REPO[Repositories<br/>Order, Menu, Customer]
        STOR[Storage<br/>File, MongoDB, Memory]
    end

    API --> APP
    APP --> DOM
    APP --> INT

    APP --> CMD
    APP --> QRY

    DOM --> EVT
    EVT --> HDL

    INT --> REPO
    REPO --> STOR

    style API fill:#e3f2fd
    style APP fill:#f3e5f5
    style DOM fill:#e8f5e8
    style INT fill:#fff3e0

🚀 Pattern Integration¶

How Patterns Work Together¶

Implementation Order¶

flowchart LR
    A[1. Clean Architecture<br/>🏗️ Layer Structure] --> B[2. Dependency Injection<br/>💉 Service Management]
    B --> C[3. CQRS & Mediation<br/>📡 Commands & Queries]
    C --> D[4. Event-Driven<br/>🔄 Domain Events]
    D --> E[5. Event Sourcing<br/>🎯 Event Persistence]
    E --> F[6. Reactive Programming<br/>🌊 Stream Processing]
    F --> G[7. Repository Pattern<br/>💾 Data Access]
    G --> H[8. Resource-Oriented<br/>🌐 API Design]
    H --> I[9. Watcher Patterns<br/>👀 Reactive Management]

    style A fill:#e8f5e8
    style B fill:#f8bbd9
    style C fill:#e3f2fd
    style D fill:#fff3e0
    style E fill:#ffecb5
    style F fill:#b3e5fc
    style G fill:#f3e5f5
    style H fill:#e1f5fe
    style I fill:#fce4ec

🎯 Business Domain Examples¶

🧪 Testing Strategies¶

📚 Pattern Learning Paths¶

🔗 Related Documentation¶

• 🚀 Framework Features - Implementation-specific features
• 📖 Implementation Guides - Step-by-step tutorials
• 🍕 Mario's Pizzeria - Complete system example
• 💼 Sample Applications - Production-ready examples
• 🔐 OAuth, OIDC & JWT - Authentication and authorization patterns

These patterns form the architectural foundation for building maintainable, testable, and scalable applications. Each pattern page includes detailed code examples, Mermaid diagrams, and practical implementation guidance using the Mario's Pizzeria domain.