Marventa.Framework 3.0.0

🚀 Marventa Framework

Enterprise-grade .NET framework implementing Clean Architecture and SOLID principles with 47+ modular features

🎯 Overview

Marventa Framework is a comprehensive, production-ready .NET framework designed for enterprise applications. Built with Clean Architecture principles, SOLID design patterns, and extensive configurability, it provides everything needed to build scalable, maintainable web applications.

📋 Table of Contents

• 🎯 Overview
• ⚡ Quick Start
• 🏗️ Architecture
• 📚 Features
• ⚙️ Configuration
• 🛡️ Security
• 📈 Performance
• 🧪 Testing
• 📖 Documentation
• 🤝 Contributing
• 📄 License

⚡ Quick Start

Installation

dotnet add package Marventa.Framework

Basic Setup

1. Configure appsettings.json:

{
  "Marventa": {
    "ApiKey": "your-secret-api-key-here",
    "RateLimit": {
      "MaxRequests": 100,
      "WindowMinutes": 15
    },
    "Caching": {
      "Provider": "Memory"
    },
    "Storage": {
      "Provider": "LocalFile",
      "BasePath": "uploads"
    }
  },
  "ConnectionStrings": {
    "Redis": "localhost:6379",
    "DefaultConnection": "your-database-connection"
  },
  "Cors": {
    "Origins": ["https://yourdomain.com", "https://localhost:3000"]
  }
}

2. Configure Services in Program.cs:

using Marventa.Framework.Web.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Configure Marventa Framework with Clean Architecture
builder.Services.AddMarventaFramework(builder.Configuration, options =>
{
    // 🏗️ Core Infrastructure (6 features)
    options.EnableLogging = true;                    // Structured logging with Serilog
    options.EnableCaching = true;                    // Memory/Redis caching
    options.EnableRepository = true;                 // Repository pattern
    options.EnableHealthChecks = true;              // Health monitoring
    options.EnableValidation = true;                // Input validation
    options.EnableExceptionHandling = true;         // Global exception handling

    // 🛡️ Security & Authentication (4 features)
    options.EnableSecurity = true;                  // Core security services
    options.EnableJWT = true;                       // JWT authentication
    options.EnableApiKeys = true;                   // API key management
    options.EnableEncryption = true;                // Data encryption

    // 📡 Communication Services (3 features)
    options.EnableEmail = true;                     // Email delivery
    options.EnableSMS = true;                       // SMS notifications
    options.EnableHttpClient = true;                // Enhanced HTTP client

    // 💾 Data & Storage (5 features)
    options.EnableStorage = true;                   // File storage
    options.EnableFileProcessor = true;             // File processing
    options.EnableMetadata = true;                  // File metadata
    options.EnableDatabaseSeeding = true;           // Database seeding
    options.EnableSeeding = true;                   // Data seeding

    // 🌐 API Management (4 features)
    options.EnableVersioning = true;                // API versioning
    options.EnableRateLimiting = true;              // Rate limiting
    options.EnableCompression = true;               // Response compression
    options.EnableIdempotency = true;               // Idempotency handling

    // ⚡ Performance & Scalability (5 features)
    options.EnableDistributedLocking = true;        // Distributed locks
    options.EnableCircuitBreaker = true;            // Circuit breaker pattern
    options.EnableBatchOperations = true;           // Batch processing
    options.EnableAdvancedCaching = true;           // Advanced caching
    options.EnableCDN = true;                       // CDN integration

    // 📊 Monitoring & Analytics (4 features)
    options.EnableAnalytics = true;                 // Usage analytics
    options.EnableObservability = true;             // Distributed tracing
    options.EnableTracking = true;                  // Event tracking
    options.EnableFeatureFlags = true;              // Feature flags

    // 🔄 Background Processing (3 features)
    options.EnableBackgroundJobs = true;            // Background jobs
    options.EnableMessaging = true;                 // Message queuing
    options.EnableDeadLetterQueue = true;           // Dead letter handling

    // 🏢 Enterprise Architecture (5 features)
    options.EnableMultiTenancy = true;              // Multi-tenancy
    options.EnableEventDriven = true;               // Event-driven architecture
    options.EnableCQRS = true;                      // CQRS pattern
    options.EnableSagas = true;                     // Saga orchestration
    options.EnableProjections = true;               // Event projections

    // 🔍 Search & AI (3 features)
    options.EnableSearch = true;                    // Full-text search
    options.EnableML = true;                        // Machine learning
    options.EnableRealTimeProjections = true;       // Real-time projections

    // 💼 Business Features (5 features)
    options.EnableECommerce = true;                 // E-commerce features
    options.EnablePayments = true;                  // Payment processing
    options.EnableShipping = true;                  // Shipping management
    options.EnableFraudDetection = true;            // Fraud detection
    options.EnableInternationalization = true;      // Internationalization

    // 🔧 Middleware Configuration
    options.MiddlewareOptions.UseUnifiedMiddleware = true;  // High performance mode
});

var app = builder.Build();

// Configure middleware pipeline with Clean Architecture
app.UseMarventaFramework(builder.Configuration);
app.Run();

3. Test your application:

# Start your application
dotnet run

# Test endpoints
curl -H "X-API-Key: your-secret-api-key-here" https://localhost:5001/health
curl -H "X-API-Key: your-secret-api-key-here" https://localhost:5001/

4. Ready to use! Your application now includes:

• ✅ Enterprise Middleware Pipeline (rate limiting, authentication, logging)
• ✅ Clean Architecture Structure (SOLID principles)
• ✅ Configuration-Driven Setup (no hard-coded values)
• ✅ Production-Ready Security (API keys, CORS, headers)
• ✅ Performance Optimization (caching, compression)
• ✅ Health Monitoring (health checks, logging)

🏗️ Architecture

Clean Architecture Implementation

┌─────────────────────────────────────────────────────────┐
│                    Presentation Layer                    │
│  ┌─────────────────┐  ┌─────────────────────────────────┐ │
│  │   Controllers   │  │         Middleware              │ │
│  │                 │  │  • Authentication              │ │
│  └─────────────────┘  │  • Rate Limiting               │ │
│                       │  • Exception Handling          │ │
│                       │  • Request/Response Logging    │ │
│                       └─────────────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│                   Application Layer                     │
│  ┌─────────────────┐  ┌─────────────────────────────────┐ │
│  │    Services     │  │         Commands/Queries       │ │
│  │  • Email        │  │  • CQRS Pattern               │ │
│  │  • SMS          │  │  • Validation                 │ │
│  │  • File Proc.   │  │  • Business Logic             │ │
│  └─────────────────┘  └─────────────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│                   Infrastructure Layer                  │
│  ┌─────────────────┐  ┌─────────────────────────────────┐ │
│  │    Storage      │  │         External Services      │ │
│  │  • Local Files  │  │  • Redis                      │ │
│  │  • Cloud        │  │  • Email Providers            │ │
│  │  • Database     │  │  • SMS Providers              │ │
│  └─────────────────┘  └─────────────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│                      Domain Layer                       │
│  ┌─────────────────────────────────────────────────────┐ │
│  │              Core Business Logic                    │ │
│  │  • Entities  • Value Objects  • Domain Services   │ │
│  │  • Business Rules  • Domain Events               │ │
│  └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

SOLID Principles Implementation

• Single Responsibility: Each service class has one reason to change
• Open/Closed: Extensible through interfaces, closed for modification
• Liskov Substitution: All implementations are substitutable
• Interface Segregation: Small, focused interfaces
• Dependency Inversion: Depends on abstractions, not concretions

📚 Features (47 Total)

🏗️ Core Infrastructure (6 Features)

🛡️ Security & Authentication (4 Features)

📡 Communication Services (3 Features)

💾 Data & Storage (5 Features)

🌐 API Management (4 Features)

⚡ Performance & Scalability (5 Features)

📊 Monitoring & Analytics (4 Features)

🔄 Background Processing (3 Features)

🏢 Enterprise Architecture (5 Features)

🔍 Search & AI (3 Features)

💼 Business Features (5 Features)

⚙️ Configuration

Application Settings Structure

{
  "Marventa": {
    // Authentication & Security
    "ApiKey": "your-api-key",
    "ApiKeys": ["key1", "key2", "key3"],
    "ApiKey": {
      "SkipPaths": ["/health", "/swagger"]
    },

    // Rate Limiting
    "RateLimit": {
      "MaxRequests": 100,
      "WindowMinutes": 15
    },

    // Caching Configuration
    "Caching": {
      "Provider": "Memory",  // "Memory" or "Redis"
      "DefaultExpirationMinutes": 30
    },

    // Storage Configuration
    "Storage": {
      "Provider": "LocalFile",  // "LocalFile" or "Cloud"
      "BasePath": "uploads",
      "MaxFileSizeBytes": 10485760
    },

    // Feature Flags
    "Features": {
      "EnableRateLimiting": true,
      "EnableApiKeys": true,
      "EnableCaching": true,
      "EnableLogging": true
    }
  },

  // Connection Strings
  "ConnectionStrings": {
    "DefaultConnection": "your-database-connection",
    "Redis": "localhost:6379",
    "Storage": "your-storage-connection"
  },

  // CORS Configuration
  "Cors": {
    "Origins": [
      "https://yourdomain.com",
      "https://localhost:3000"
    ]
  }
}

Environment-Specific Configuration

// appsettings.Development.json
{
  "Marventa": {
    "RateLimit": {
      "MaxRequests": 1000,
      "WindowMinutes": 1
    },
    "Caching": {
      "Provider": "Memory"
    }
  }
}

// appsettings.Production.json
{
  "Marventa": {
    "RateLimit": {
      "MaxRequests": 100,
      "WindowMinutes": 15
    },
    "Caching": {
      "Provider": "Redis"
    }
  },
  "ConnectionStrings": {
    "Redis": "production-redis-connection"
  }
}

🛡️ Security

Built-in Security Features

• 🔐 API Key Authentication: Multiple API keys with path exclusions
• 🛡️ Rate Limiting: Configurable request throttling per user/IP
• 📋 CORS: Flexible cross-origin resource sharing
• 🔒 Security Headers: OWASP-compliant HTTP headers
• 🚫 Input Validation: Request validation and sanitization
• 📝 Request Logging: Comprehensive request/response logging
• 🔑 JWT Support: Token-based authentication (optional)

Security Headers Applied

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
X-Powered-By: Marventa.Framework

📈 Performance

Performance Features

• ⚡ Unified Middleware: Single-pass middleware for optimal performance
• 💾 Smart Caching: Memory + Redis with automatic fallback
• 🗜️ Response Compression: Automatic GZIP compression
• 🔄 Connection Pooling: Efficient database connections
• 📊 Performance Monitoring: Built-in performance metrics

Benchmark Results

🧪 Testing

Running Tests

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific category
dotnet test --filter Category=Integration

Test Structure

Marventa.Framework.Tests/
├── Unit/
│   ├── Services/
│   ├── Middleware/
│   └── Extensions/
├── Integration/
│   ├── Api/
│   ├── Database/
│   └── Storage/
└── Performance/
    ├── Load/
    └── Stress/

📖 Documentation

Additional Resources

• API Reference: Complete API documentation
• Configuration Guide: Detailed configuration options
• Best Practices: Enterprise development guidelines
• Migration Guide: Upgrading from previous versions
• Examples: Sample applications and use cases

💻 Usage Examples

🚀 CDN Service Integration

Configure multiple CDN providers and use them seamlessly:

{
  "Marventa": {
    "CDN": {
      "Provider": "Azure", // "Azure", "AWS", "CloudFlare"
      "Azure": {
        "SubscriptionId": "your-subscription-id",
        "ResourceGroup": "your-resource-group",
        "StorageAccount": "your-storage-account",
        "ContainerName": "cdn-content",
        "ProfileName": "your-cdn-profile",
        "EndpointName": "your-endpoint",
        "AccessToken": "your-access-token"
      },
      "AWS": {
        "AccessKeyId": "your-access-key",
        "SecretAccessKey": "your-secret-key",
        "Region": "us-east-1",
        "S3Bucket": "your-s3-bucket",
        "DistributionId": "your-cloudfront-distribution-id",
        "CloudFrontDomain": "your-domain.cloudfront.net"
      },
      "CloudFlare": {
        "ApiToken": "your-api-token",
        "ZoneId": "your-zone-id",
        "AccountId": "your-account-id",
        "R2Bucket": "your-r2-bucket",
        "CustomDomain": "your-custom-domain.com"
      }
    }
  }
}

// Use CDN service in your controllers
[ApiController]
[Route("api/[controller]")]
public class FilesController : ControllerBase
{
    private readonly IMarventaCDN _cdnService;

    public FilesController(IMarventaCDN cdnService)
    {
        _cdnService = cdnService;
    }

    [HttpPost("upload")]
    public async Task<IActionResult> UploadFile(IFormFile file)
    {
        using var stream = file.OpenReadStream();

        var options = new CDNUploadOptions
        {
            CacheControl = "public, max-age=3600",
            EnableCompression = true,
            AccessLevel = CDNAccessLevel.Public
        };

        var result = await _cdnService.UploadToCDNAsync(
            fileId: Guid.NewGuid().ToString(),
            content: stream,
            contentType: file.ContentType,
            options: options
        );

        if (result.Success)
        {
            return Ok(new {
                url = result.CDNUrl,
                fileId = result.CDNFileId,
                regionalUrls = result.RegionalUrls
            });
        }

        return BadRequest(result.ErrorMessage);
    }

    [HttpGet("{fileId}/metrics")]
    public async Task<IActionResult> GetMetrics(string fileId, [FromQuery] DateTime? startDate, [FromQuery] DateTime? endDate)
    {
        var timeRange = new TimeRange
        {
            StartTime = startDate ?? DateTime.UtcNow.AddDays(-7),
            EndTime = endDate ?? DateTime.UtcNow
        };

        var metrics = await _cdnService.GetMetricsAsync(fileId, timeRange);
        return Ok(metrics);
    }
}

🔄 Saga Pattern for Distributed Transactions

Implement complex business processes with compensating transactions:

// Define your saga
public class OrderProcessingSaga : ISaga
{
    public Guid CorrelationId { get; set; } = Guid.NewGuid();
    public SagaStatus Status { get; set; } = SagaStatus.Started;
    public string CurrentStep { get; set; } = string.Empty;
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
    public DateTime? CompletedAt { get; set; }
    public List<string> CompletedSteps { get; set; } = new();
    public string? ErrorMessage { get; set; }

    // Business properties
    public string OrderId { get; set; } = string.Empty;
    public string CustomerId { get; set; } = string.Empty;
    public decimal TotalAmount { get; set; }
    public string? PaymentId { get; set; }
    public string? InventoryReservationId { get; set; }
    public string? ShipmentId { get; set; }
}

// Create saga orchestrator
public class OrderProcessingOrchestrator : ISagaOrchestrator<OrderProcessingSaga>
{
    private readonly IPaymentService _paymentService;
    private readonly IInventoryService _inventoryService;
    private readonly IShippingService _shippingService;

    public async Task HandleAsync(OrderProcessingSaga saga, object @event, CancellationToken cancellationToken)
    {
        switch (@event)
        {
            case OrderCreatedEvent orderCreated:
                await ProcessPayment(saga, orderCreated);
                break;
            case PaymentCompletedEvent paymentCompleted:
                await ReserveInventory(saga, paymentCompleted);
                break;
            case InventoryReservedEvent inventoryReserved:
                await CreateShipment(saga, inventoryReserved);
                break;
            case ShipmentCreatedEvent shipmentCreated:
                await CompleteOrder(saga, shipmentCreated);
                break;
        }
    }

    public async Task CompensateAsync(OrderProcessingSaga saga, string reason, CancellationToken cancellationToken)
    {
        // Compensate in reverse order
        if (saga.CompletedSteps.Contains("ShipmentCreated"))
            await CancelShipment(saga);

        if (saga.CompletedSteps.Contains("InventoryReserved"))
            await ReleaseInventory(saga);

        if (saga.CompletedSteps.Contains("PaymentProcessed"))
            await RefundPayment(saga);
    }
}

// Use in your controllers
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly ISagaManager _sagaManager;

    public OrdersController(ISagaManager sagaManager)
    {
        _sagaManager = sagaManager;
    }

    [HttpPost]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
        var orderCreatedEvent = new OrderCreatedEvent(
            request.OrderId,
            request.CustomerId,
            request.TotalAmount
        );

        var saga = await _sagaManager.StartSagaAsync<OrderProcessingSaga>(orderCreatedEvent);

        return Ok(new {
            orderId = request.OrderId,
            sagaId = saga.CorrelationId,
            status = saga.Status
        });
    }

    [HttpGet("{sagaId}/status")]
    public async Task<IActionResult> GetOrderStatus(Guid sagaId)
    {
        var status = await _sagaManager.GetSagaStatusAsync<OrderProcessingSaga>(sagaId);
        return Ok(new { sagaId, status });
    }
}

💾 Repository Pattern with Clean Architecture

Access data with strongly-typed repositories:

// Use repository in your services
public class ProductService
{
    private readonly IRepository<Product> _productRepository;
    private readonly IMarventaCaching _cache;

    public ProductService(IRepository<Product> productRepository, IMarventaCaching cache)
    {
        _productRepository = productRepository;
        _cache = cache;
    }

    public async Task<Product?> GetByIdAsync(Guid id)
    {
        var cacheKey = $"product_{id}";

        var cached = await _cache.GetAsync<Product>(cacheKey);
        if (cached != null) return cached;

        var product = await _productRepository.GetByIdAsync(id);
        if (product != null)
        {
            await _cache.SetAsync(cacheKey, product, TimeSpan.FromMinutes(30));
        }

        return product;
    }

    public async Task<IEnumerable<Product>> GetByCategoryAsync(string category)
    {
        return await _productRepository.FindAsync(p => p.Category == category);
    }

    public async Task<Product> CreateAsync(Product product)
    {
        var created = await _productRepository.AddAsync(product);
        await _productRepository.SaveChangesAsync();

        // Invalidate category cache
        await _cache.RemoveByPatternAsync($"products_category_{product.Category}*");

        return created;
    }
}

// Use in controllers
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly ProductService _productService;

    public ProductsController(ProductService productService)
    {
        _productService = productService;
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetProduct(Guid id)
    {
        var product = await _productService.GetByIdAsync(id);
        if (product == null)
            return NotFound();

        return Ok(product);
    }

    [HttpGet]
    public async Task<IActionResult> GetByCategory([FromQuery] string category)
    {
        var products = await _productService.GetByCategoryAsync(category);
        return Ok(products);
    }

    [HttpPost]
    public async Task<IActionResult> CreateProduct(Product product)
    {
        var created = await _productService.CreateAsync(product);
        return CreatedAtAction(nameof(GetProduct), new { id = created.Id }, created);
    }
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/your-org/marventa-framework.git

# Navigate to the project
cd marventa-framework

# Restore packages
dotnet restore

# Build the solution
dotnet build

# Run tests
dotnet test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏆 Why Choose Marventa Framework?

<div align="center">

Built with ❤️ by the Marventa Team

Website • Documentation • Support

</div>