bitzorcas
中EN

Concept

Building Blocks Map and Architectural Philosophy

A comprehensive overview of BitzOrcas.Modern core building blocks, spanning Unified Aggregates, QueryShape read models, CAP Outbox, multi-level caching, and S3 storage.

Last updated

In modern enterprise modular monoliths, foundational building blocks dictate overall architectural resilience.

The building-blocks/ directory compiles the production-tested building blocks powering BitzOrcas.Modern. Every block enforces “Typed Contracts, Zero Unnecessary Reflection, Multi-Tenant Safety, and Secure Defaults”.

Building Blocks Map

4. Developer Ergonomics

OpenAPI 3.1 & Scalar (openapi-scalar)

3. Concurrency & Storage

FusionCache Multi-Level Cache (caching)

Redis Distributed Lock (distributed-locking)

S3/MinIO Object Storage (storage)

Tenant Quotas & Limits (quota)

2. Messaging & Jobs

CAP Outbox Event Bus (eventing)

Database Background Jobs (jobs)

1. Domain & Persistence

Core Primitives & Clocks (core)

Unified Aggregates (unified-aggregate)

QueryShape Read Models (query-shape)

Building Block Directory

1. Core Domain Primitives and Clocks

  • Entity, AggregateRoot, and TenantAggregateRoot hierarchies;
  • Typed Result and Error flow control;
  • Deterministic IAppClock preventing timezone drift.

2. Unified Aggregate Root and Persistence Kernel

  • Eliminate redundant 1:1 *Entity and Mapper boilerplate;
  • Roslyn generators emit EF Core and SqlSugar configurations during compilation;
  • Value object flattening and automatic audit interceptors.

3. Standard List Query Kernel and QueryShape

  • IDeclareQueryShape declarative shapes with compile-time execution plans;
  • Dual-ORM projections pushed down to SQL column levels;
  • Normalized paging boundaries (1 to 1000).

4. Event Bus and CAP Outbox

  • In-process domain events vs cross-module integration events;
  • Transactional Outbox pattern guaranteeing atomic writes and zero message loss;
  • Idempotent consumer deduplication.

5. Multi-Level Caching with FusionCache

  • In-memory L1 and Redis L2 tiered caching;
  • Negative caching and single-flight stampede defense;
  • Post-commit tag-based invalidation.

6. Distributed Locking and Deadlock Prevention

  • IDistributedLock typed handles with await using disposal;
  • Redis atomic acquisition and owner-checked Lua releases;
  • Lease renewals and fallback degradation policies.

7. Database-Driven Background Jobs (Quartz)

  • Scheduler-agnostic IJobExecutor<T> handlers;
  • Quartz clustered persistence guaranteeing single-instance execution;
  • Operations probes and graceful shutdown.

8. S3 Object Storage and Presigned URLs

  • IFileStorage unified port (Local / MinIO / S3);
  • Presigned direct uploads with zero API bandwidth overhead;
  • Multi-tenant bucket security and IDOR defense.

9. Tenant Quotas and Rate Limiting

  • Token bucket algorithm and burst allowances;
  • Host-level RedisTokenBucket rate limiting plus PlatformBilling QuotaService quota checks;
  • Graceful 429 Too Many Requests enforcement.

10. OpenAPI 3.1 and Scalar Modern Documentation

  • [GenerateEndpoint] compile-time metadata extraction;
  • Zero reflection under Native AOT;
  • Modern, interactive Scalar API console.

Chapter Navigation

100%

Scroll or use controls to zoom · drag when enlarged · double-click for 100% / 200%