Uncategorized

Hazina Architecture: Best Practices and a Complete Application Example

Over the last 19 posts, we’ve covered every major feature of Hazina. In this final post, we’ll tie it all together with architectural best practices and a complete example of a production application built on Hazina.

Recommended Project Structure

MyApp/
â"œâ"€â"€ MyApp.API/                  # ASP.NET Core web API
â"‚   â"œâ"€â"€ Controllers/            # Custom controllers (extend GenericEntityController)
â"‚   â"œâ"€â"€ Program.cs              # Hazina configuration
â"‚   â - â"€â"€ appsettings.json        # Environment-specific settings
â"œâ"€â"€ MyApp.Core/                 # Business logic
â"‚   â"œâ"€â"€ Entities/               # Entity definitions
â"‚   â"œâ"€â"€ Services/               # Business services
â"‚   â - â"€â"€ Tools/                  # Agent tools
â"œâ"€â"€ MyApp.Infrastructure/       # External concerns
â"‚   â"œâ"€â"€ Data/                   # DbContext, migrations
â"‚   â - â"€â"€ Providers/              # External API integrations
â - â"€â"€ MyApp.Tests/                # Test project
    â"œâ"€â"€ Unit/
    â - â"€â"€ Integration/

Complete Program.cs Example

var builder = WebApplication.CreateBuilder(args);

// Database
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Default")));

// Hazina
builder.Services.AddHazina(config => {
    config.AI.SetupFromConfiguration(builder.Configuration);
    config.Storage.UsePostgreSQL(builder.Configuration.GetConnectionString("Default")!);
});

// Generic API
builder.Services.AddGenericEntityApi<AppDbContext>();
builder.Services.AddScoped<ITenantContext, TenantContext>();

// Plugins
builder.Services.AddHazinaPlugins();

// Health checks
builder.Services.AddHazinaHealthChecks();

// Auth
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.UseGenericEntityApi();
app.MapControllers();
app.MapHealthChecks("/health");

app.Run();

The 5 Principles of Hazina Architecture

  1. Start simple, scale up – Use SQLite and QuickSetup for development. Switch to PostgreSQL and full config for production.
  2. Convention over configuration – Don’t configure what works by default. Only override what’s different.
  3. Layer your entities – Use the right base class. Don’t add multi-tenancy to lookup tables. Don’t skip soft delete on business entities.
  4. Let the framework handle CRUD – Only write custom controllers for non-standard operations. Everything else gets GenericEntityController.
  5. Monitor everything – Health checks, structured logging, and metrics aren’t optional in production.

What We’ve Covered

# Topic Key Takeaway
1 Introduction Hazina = AI + API + Infrastructure for .NET
2 Quick Start Zero to AI call in 5 minutes
3 FluentAPI One interface for all LLM providers
4 Configuration Layered, overridable, validated
5 Generic API Full CRUD in one line
6 Entity Types Soft delete, tenant, ownership built in
7 Multi-Tenancy Automatic data isolation
8 RAG Engine Smart document search
9 Document Store Persistent knowledge base
10 Dynamic Plugins Runtime code generation with Roslyn
11 Plugin Security Sandboxed, whitelisted, audited
12 Orchestration Autonomous AI agents with tools
13 Social Providers Unified content import
14 Content Analysis AI-powered style and topic detection
15 Observability Health checks, metrics, cost tracking
16 EF Core Seamless database integration
17 Production Deployment patterns and scaling
18 YAML Entities Non-developer entity definitions
19 Developer Tools CLI, demos, testing utilities
20 Best Practices Architecture for real-world apps

What’s Next?

Hazina is actively developed and new features are being added regularly. Check the GitHub repository for the latest updates, and don’t hesitate to open issues or contribute.

Happy building!

Terug naar overzicht
ENNL