⚡ BlazorEnterprise

Enterprise Cloud-Native SaaS Starter Kit & Reference Architecture
Built with .NET 10, Interactive Server Blazor, Microsoft Fluent UI Blazor V5, EF Core 10, PostgreSQL Native RLS, and .NET Aspire Orchestration.

---

🎯 What is BlazorEnterprise?

BlazorEnterprise is an enterprise-grade, security-hardened starter kit and reference architecture designed for organizations building mission-critical multi-tenant SaaS applications, internal portals, and governance platforms.

Rather than providing simple CRUD templates, BlazorEnterprise delivers production-grade enterprise subsystems:

• 🐘 Layer 5 Defense-in-Depth (PostgreSQL Native RLS): Tenant isolation is physically guaranteed at the database engine level via TenantDbConnectionInterceptor and native PostgreSQL Row-Level Security policies.
• 📐 Clean Architecture (12-Project Topology): Strictly enforced inward dependency direction, separating domain core, persistence, infrastructure, API gateway, standalone worker host, and orchestration.
• ☁️ .NET Aspire Orchestration: Turnkey local orchestration with distributed OpenTelemetry tracing, live metrics, and dual-mode database routing (Native Local PostgreSQL vs Docker containerized PostgreSQL/pgAdmin).
• ⚙️ Dual-Mode Asynchronous Worker Host (BlazorEnterprise.Worker): Thin standalone console host shell (net10.0 Worker SDK) for distributed, horizontally scalable background queues with zero code duplication from BlazorEnterprise.Jobs.
• 🔐 Zero-Trust Multi-Tenancy Isolation: Ephemeral 5-minute S2S JWTs signed via private TenantLicenseKey, dynamic API key resolver, masked claims (tid: tnt_..., zero PII), and cross-tenant quarantine barriers.
• ⚡ 100% In-Memory Rules Engine (BlazorEnterprise.RulesEngine): Sub-millisecond calculation pipeline for regulatory, financial, and business rule evaluations with zero database contention.
• 🔐 Zero-Knowledge Envelope Encryption: Hardware-accelerated AES-256-GCM authenticated stream encryption with dynamic per-tenant keys derived via HKDF-SHA256.
• ⏱️ Thread-Isolated Asynchronous Ingestion: Bounded System.Threading.Channels queues with a 4-stage batch pipeline (Ingestion -> Queue -> Validation/Staging -> Domain Promotion).
• 🎨 Microsoft Fluent UI Blazor V5: Modern Microsoft Fluent 2 design language with zero legacy V4 tokens, custom design tokens, and automated Roslyn compliance verification.
• 🛡️ TemplateGuard Governance: Custom Roslyn Analyzer and AST manifest locking (.basefiles.json) that protects core files while enabling downstream customizations via .Custom.cs partial classes.

---

🏗️ 12-Project Solution Architecture

BlazorEnterprise strictly follows Clean Architecture dependency boundaries where all dependencies flow inward toward the domain core:

flowchart TD
    subgraph Orchestration ["Orchestration & Diagnostics"]
        AppHost["BlazorEnterprise.AppHost\n(Aspire 13.4 Host)"]
        Defaults["BlazorEnterprise.ServiceDefaults\n(OpenTelemetry & Health)"]
    end

    subgraph Presentation ["Presentation Layer"]
        Web["BlazorEnterprise.Web\n(Interactive Server Blazor, Fluent UI V5)"]
        Templates["BlazorEnterprise.UI.Templates\n(Enterprise Wizard RCL)"]
    end

    subgraph BusinessAndApi ["Business Services, API Gateway & Background Processing"]
        Api["BlazorEnterprise.Api\n(ProcessAPI, Multi-IdP Auth Gateway)"]
        Rules["BlazorEnterprise.RulesEngine\n(In-Memory Calculation Engine)"]
        Jobs["BlazorEnterprise.Jobs\n(Channel Batch Queue, File Ingestion)"]
        Worker["BlazorEnterprise.Worker\n(Standalone Background Host Shell)"]
    end

    subgraph DataAndInfra ["Persistence & Infrastructure"]
        Infra["BlazorEnterprise.Infrastructure\n(Notifications, S2S Auth Handlers)"]
        Persist["BlazorEnterprise.Persistence\n(PostgreSQL AppDbContext, Interceptors)"]
    end

    subgraph CoreRing ["Domain Core & Shared Primitives"]
        Core["BlazorEnterprise.Core\n(Domain Entities, Interfaces, Validation)"]
        Shared["BlazorEnterprise.Shared\n(Cross-Cutting DTOs, Security Envelopes)"]
    end

    AppHost --> Web
    AppHost --> Api
    Web --> Defaults
    Api --> Defaults
    Worker --> Defaults
    Web --> Templates
    Web --> Jobs
    Web --> Infra
    Web --> Persist
    Web --> Core
    Web --> Shared
    Worker --> Jobs
    Worker --> Persist
    Worker --> Infra
    Worker --> Core
    Worker --> Shared
    Api --> Core
    Api --> Shared
    Rules --> Shared
    Jobs --> Persist
    Jobs --> Core
    Jobs --> Shared
    Infra --> Core
    Infra --> Shared
    Persist --> Core
    Persist --> Shared
    Core --> Shared

Loading

Solution Project Directory:

Project	Target Framework	Purpose
BlazorEnterprise.Shared	net10.0	Cross-cutting domain enums, security DTOs, encryption contracts, and common models.
BlazorEnterprise.Core	net10.0	Pure domain entities, business service interfaces, OpaqueIdUtility, and FluentValidation rules.
BlazorEnterprise.Persistence	net10.0	PostgreSQL AppDbContext, EF Core RLS interceptors, and HybridCache (L1/L2).
BlazorEnterprise.Infrastructure	net10.0	S2S TenantTokenService, TenantAuthDelegatingHandler, notifications (SMTP/Teams), and circuit security.
BlazorEnterprise.Jobs	net10.0	Bounded Channel batch queue, Cronos periodic schedulers, and 4-stage file ingestion library.
BlazorEnterprise.Worker	net10.0	Thin standalone console host shell executing background queues with horizontal scalability.
BlazorEnterprise.Web	net10.0	Web application host, 65+ Fluent UI V5 components, and role authorization contracts.
BlazorEnterprise.UI.Templates	net10.0	Decoupled Razor Class Library (RCL) housing the Enterprise Wizard framework.
BlazorEnterprise.RulesEngine	net10.0	Company Azure 100% in-memory CPU calculation routines with sub-millisecond execution.
BlazorEnterprise.Api	net10.0	ProcessAPI with dynamic IssuerSigningKeyResolver, Multi-IdP Auth Gateway, and Key Vault management.
BlazorEnterprise.ServiceDefaults	net10.0	Shared Aspire OpenTelemetry metrics, distributed tracing, and health checks.
BlazorEnterprise.AppHost	net10.0	Aspire 13.4 Orchestrator host managing multi-project lifecycles and database routing.

---

🛡️ 5-Layer Defense-in-Depth Security

Security is enforced at every tier of the stack to ensure fail-closed isolation:

flowchart TD
    Req([Inbound Request]) --> L1
    
    subgraph L1 ["1. Edge & HTTP Security"]
        L1a["Strict Content-Security-Policy (CSP) & HSTS"]
        L1b["Antiforgery Tokens & HTML Input Sanitization"]
    end
    
    L1 --> L2
    subgraph L2 ["2. Identity & Centralized Auth Gateway"]
        L2a["Multi-IdP Federation (Entra ID, OIDC, Dev Switcher)"]
        L2b["HMAC-SHA256 Cryptographic Tokens"]
    end
    
    L2 --> L3
    subgraph L3 ["3. UI Page Contracts"]
        L3a["AuthorizedPageComponentBase"]
        L3b["MinimumVisitRole & MinimumEditRole Guards"]
    end
    
    L3 --> L4
    subgraph L4 ["4. Domain Service Gates"]
        L4a["EnsureCanEditAsync & Audit Diff Logging"]
        L4b["ProjectSecurityInterceptor (EF Core Write Guard)"]
    end
    
    L4 --> L5
    subgraph L5 ["5. PostgreSQL Native Row-Level Security"]
        L5a["TenantDbConnectionInterceptor (SET LOCAL app.current_tenant_id)"]
        L5b["Database Engine Physical Cross-Tenant Rejection"]
    end
    
    L5 --> DB[(PostgreSQL Database)]

Loading

---

⚡ Asynchronous Ingestion & Stream Encryption Pipeline

flowchart LR
    A["1. Client Upload\n(Blazor UI)"] -->|Event Notification| B["2. Channel Queue\n(System.Threading.Channels)"]
    B --> C["3. Validation & Staging\n(Excel/CSV Fail-Closed Staging)"]
    C --> D["4. Domain Promotion\n(Live Business Entities)"]
    
    subgraph Crypto ["Hardware-Accelerated Envelope Encryption"]
        E["AES-256-GCM Stream + Per-Tenant HKDF-SHA256 Key"]
    end
    A -.-> Crypto

Loading

---

🚀 5-Minute Quickstart

1. Prerequisites

• .NET 10 SDK (net10.0)
• PostgreSQL 16+ installed locally OR Docker Desktop

2. Configure Database Routing

BlazorEnterprise dynamically supports both Native Local PostgreSQL and Docker Containerized PostgreSQL in src/BlazorEnterprise.AppHost/appsettings.json:

{
  "Aspire": {
    "UseDockerPostgres": false
  },
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=blazorenterprise_db;Username=postgres;Password=<your_password>;Pooling=true;"
  }
}

• Set "UseDockerPostgres": false to run natively on localhost:5432 with zero Docker dependencies.
• Set "UseDockerPostgres": true if you prefer Aspire to spin up containerized PostgreSQL and pgAdmin.

3. Launch with Aspire Orchestration

Set src/BlazorEnterprise.AppHost as the Startup Project and press F5 (or Ctrl+F5 to start without debugging).

The Aspire Telemetry Dashboard opens automatically, displaying running endpoints, live traces, and metrics. Click on web to access the application.

---

🛠️ Repository Automation Scripts

Script	Purpose
Rename-Project.ps1	Automates rebranding the entire solution, namespaces, directories, and configuration files.
scripts/build-templateguard.ps1	Compiles the TemplateGuard Roslyn analyzer and AST manifest tool.
scripts/generate-base-manifest.ps1	Generates the locked .basefiles.json AST fingerprint for template authoring.
scripts/Generate-DataModelDocs.ps1	Rebuilds the interactive HTML data model documentation portal and Markdown reference.
scripts/verify-fluent-v5.ps1	Roslyn AST scanner ensuring 100% compliance with Microsoft Fluent UI Blazor V5.
scripts/Download-Quill.ps1	Bundles air-gapped rich-text editor assets for offline enterprise environments.

---

📚 Documentation Index

For in-depth architectural guides, security specifications, and developer recipes, consult the BlazorEnterprise Documentation Suite:

• 00 — Overview & Executive Summary: Capabilities matrix, mental model, and personas.
• 01 — Getting Started & Setup: Prerequisites, Aspire setup, and config dictionary.
• 02 — Architecture & Project Structure: 11-project Clean Architecture specification.
• 03 — Security Model & Defense-in-Depth: PostgreSQL Native RLS, Envelope Encryption, and Auth Gateway.
• 04 — Enterprise Features & Subsystems: Channel queues, Rules Engine, and Wizard RCL.
• 05 — Observability & Reliability: Aspire OpenTelemetry, HybridCache, and audit diffs.
• 06 — UI Conventions (Fluent UI V5): 4-tier taxonomy and Fluent 2 design language.
• 07 — How-To-Extend & Developer Recipes: Copy-pasteable step-by-step developer recipes.
• 08 — Operational Scripts & Tooling: Full script catalog and usage guide.
• 09 — Coding Standards & Project Rules: Human engineering team standards and C# 13 idioms.
• 10 — AI Agent Governance & Rules: Strict operational rules and behavioral constraints for AI coding agents.