ARCHITECTURAL MANIFESTO

17 Layers of
Architectural Perfection.

A domain-agnostic blueprint for enterprise Blazor applications. From "Smart Orchestrators" in the frontend to "Vector Search" in the database. This is how we build software that lasts.

CHAPTER 01 & 02

Smart Orchestrators,
Dumb Views.

We decouple the UI from the logic. The .razor file is purely for layout. All state, API interactions, and SignalR streams are handled by a dedicated Orchestrator.

GenericListOrchestrator.cs
1public class GenericListOrchestrator<TDto> : IDisposable
2{
3 // Reactive Search Stream
4 private readonly Subject<string> _searchSubject = new();
5
6 public async Task InitializeAsync()
7 {
8 // Debounce input to prevent API flooding
9 _searchSubject
10 .Throttle(TimeSpan.FromMilliseconds(400))
11 .Subscribe(_ => ReloadServerData());
12
13 // Real-time updates via SignalR
14 _hubConnection.On<EntityUpdated>("ReceiveUpdate", ...);
15 }
16}

CHAPTER 05 & 08

The REPR Pattern &
Advanced Business Logic.

No more Fat Controllers. We use FastEndpoints to slice the application vertically. Business logic is encapsulated in behavioral facades, never in the endpoint itself.

CreateMerchantEndpoint.cs
1public class CreateMerchantEndpoint : Endpoint<CreateRequest>
2{
3 public override void Configure()
4 {
5 Post("/api/merchants");
6 AllowAnonymous();
7 }
8
9 public override async Task HandleAsync(CreateRequest r, CancellationToken c)
10 {
11 // Functional handling (No try/catch)
12 var result = await _service.CreateAsync(r);
13
14 await result.Match(
15 Right: m => SendOkAsync(m),
16 Left: err => SendErrorsAsync(err)
17 );
18 }
19}

CHAPTER 10

Metadata-Driven
Saga Orchestration.

Workflows aren't hard-coded; they are defined in JSON Recipes. Our Saga Engine handles long-running processes, compensation (undo), and real-time user assignment.

MerchantOnboardingSagaRecipe.json
1{
2 "flowType": "MerchantOnboarding",
3 "steps": [
4 {
5 "operation": "CreateStripeAccount",
6 "compensation": "DeactivateStripeAccount",
7 "policy": "RetryExponential(3)"
8 },
9 {
10 "operation": "AssignToComplianceOfficer",
11 "requires": "HumanApproval"
12 }
13 ]
14}

CHAPTER 13 & 14

Oracle 23ai &
In-Database Vectors.

We don't use external vector databases. We leverage Oracle 23ai to perform hybrid search (SQL + Vector) within the same transaction boundary. We even analyze our own code with a Roslyn RAG Console.

OracleVectorService.cs
1public async Task<List<Result>> HybridSearchAsync(string query)
2{
3 // Execute Vector Search + Relational Filter in ONE query
4 var sql = @"
5 SELECT * FROM Merchants m
6 WHERE m.Status = 'Active'
7 ORDER BY VECTOR_DISTANCE(
8 m.Embedding,
9 VECTOR_EMBEDDING(:model USING :query)
10 ) FETCH FIRST 5 ROWS ONLY";
11
12 return await _db.QueryAsync(sql, new { query });
13}

The Full 17-Layer Architecture

CH 01 & 02
UI Architecture
Generic List Orchestrators and Master-Detail State Management using MudBlazor.
CH 03 & 04
Connectivity & BI
Flurl-based HTTP Client abstraction and Analytical Pipelines for Dashboards.
CH 05
API Layer
FastEndpoints implementation using the REPR pattern and Vertical Slices.
CH 06 & 09
Data Access
Specification Pattern, Cache-Aside (Redis), and SQL-side Projections.
CH 07
Transport DTOs
Shared Kernel contracts with built-in Memento Pattern and Change Observables.
CH 08
Business Logic
Behavioral Facades that encapsulate domain rules and complex calculations.
CH 10
Saga Engine
Distributed transaction orchestration with metadata-driven recipes and SignalR.
CH 11
Identity & Auth
Granular Permission System (not just Roles) and Security Stamp invalidation.
CH 12
Infrastructure
MediatR Pipeline (Logging, Validation, Transaction), Polly, and Serilog.
CH 13 & 14
AI & Vectors
Oracle 23ai integration and the "Roslyn RAG" console for code analysis.
CH 15
Performance QA
Automated NBomber load testing suites defined as C# code.
CH 16
Reporting
Dynamic PDF composition engine using QuestPDF and Strategy Pattern.