bitzorcas
中EN
BitzOrcas.Modern · .NET 10 Enterprise Architecture
15 supported template combinations · AI-Native MCPConsumer Solution · PackageReference delivery

A modular .NET 10 architecture baseline for product teams,with clear boundaries from source to agent delivery.

BitzOrcas.Modern turns module boundaries, CQRS vertical slices, unified authorization, multitenant isolation, CAP eventing, workflow engines, multi-ORM dual-engine persistence, and AI-Native MCP protocols into composable templates. Teams use ProfileChoice to select business shapes, tenancy modes, and platform extensions, choose SqlSugar or EF Core as the runtime adapter, and generate a Consumer Solution that owns its business source without leaking framework internals.

Create your first project→Explore the architecture
  • .NET 10 / C# 14
  • ·
  • SQL Server · Redis · RabbitMQ
  • ·
  • Model Context Protocol (MCP)
bitzorcas aspire session
$

Local topology orchestrated and observed through .NET Aspire

Architecture template snapshot · 2026-09-23
  • Base solution shapes

    3

    Minimal API, single-tenant business, and multitenant business define the Host, tenancy, and deployment baseline

  • Optional extensions

    6

    Authorization, MasterData, Finance, HR, Auction, and Legal

  • Supported combinations

    15

    1 minimal API, 7 single-tenant business, and 7 multitenant business combinations

  • Platform source boundaries

    37

    Identity, authorization, workflow, AI agents, files, search, auditing, legal connectors, and more

The stack

One engineering baseline,with deliberate adapter seams.

The framework provides source- and test-verified defaults while identifying capabilities that depend on provider, topology, and operations evidence. Replacements must pass the same contracts and parity gates.

Backend Architecture

.NET 10

Minimal APIs, Mediator.SourceGenerator, and C# 14 on the latest LTS — compile-time generated, zero reflection overhead, instant startup.

Persistence · Dual Engine

SqlSugar + EF Core + Dapper

Command writes are driven by SqlSugar/EF Core adapters with built-in tenant filters and audit; read models query Dapper replicas directly.

Orchestration · ready

.NET Aspire

One command brings up SQL Server, Redis, RabbitMQ, OTLP Collector, and the API.

Deploy · baseline

Docker Compose & K8s

A reproducible container baseline with probe endpoints; production still validates secrets, restore, capacity, and multiple replicas.

Storage · S3

S3-compatible

Local storage for development and an S3-compatible adapter for production; verify metadata, hashing, and presigned semantics per provider.

Tenancy · default

Multitenancy Governance

Tenant aggregates are isolated by default and platform-wide rows are explicit; ORM, cache, jobs, and search are verified separately.

In-house · core

Workflow Engine

ORM-neutral runtime with dedicated contracts for JSON DSL, versions, deployment, tasks, history, and recovery.

AI · Native

Model Context Protocol

[GenerateMcpTool] compile-time tool generation streamed via /mcp endpoints under strict tenant scoping and permission gates.

Developer Suite · Tools

BitzOrcas.Suite Workbench

Desktop visual suite integrating ER data modeling, database DDL diff inspection, Git timeline auditing, and architectural testing.

01·CLI and solution templates

Do not copy one fixed skeleton,compose the solution the product needs.

The same bitzorcas-host template generates 15 supported combinations. ProfileChoice determines the business shape, tenancy mode, platform or industry extension, and deployment. RuntimeAdapter only selects SqlSugar or EF Core; it does not create another template combination.

CLI · create a multitenant business system
$ dotnet new bitzorcas-host -n Acme.Crm \
  --ProfileChoice default-business-multi \
  --RuntimeAdapter sqlsugar

Deterministic output

  • ProfileChoice · default-business-multi
  • RuntimeAdapter · SqlSugar
  • Hosts · Api + ServiceDefaults + AppHost
  • Business source · Modules/Business/Starter
  • Evidence · manifest + unit/architecture tests

COMPOSITION MODEL

Template combinations and ORMs are counted separately

Base shapes
3
Extensions
6
ProfileChoice
15
RuntimeAdapter
2

ProfileChoice determines the Host, module, tenancy, and deployment closure. RuntimeAdapter only switches the production ORM; it does not create another template combination.

  • MINI API

    Minimal single-tenant API

    mini-api-single

    The smallest API Host closure, without a Platform module or industry extension.

    • single
    • sqlsugar / efcore
  • BUSINESS

    Single-tenant business system

    default-business-single

    An API Host plus a Consumer-owned Starter module in a governed baseline closure.

    • single
    • sqlsugar / efcore
  • PLATFORM

    Multitenant authorization system

    default-business-multi-authorization

    The multitenant Aspire closure explicitly adds the Authorization runtime module.

    • multi
    • authorization
  • LEGAL

    Multitenant legal system

    default-business-multi-legal

    Adds the supported package-only Legal extension to the standard business closure.

    • multi
    • legal
Compare templates and use casesReview all composition parameters
02·Modular monolith + vertical slice

A modular monolith,sliced vertically.

Each module owns its Contracts, Domain, Application, Infrastructure, and Endpoint surface; other modules depend only on public contracts. Use cases are organized around Commands and Queries, keeping generated endpoints, validation pipelines, aggregate behavior, and test evidence traceable instead of scattering business logic across controllers, services, and repository scripts.

Modular monolith

Modular monolith, unified architecture

Business Modules
Platform Contracts
Identity + Tenancy
Authorization
Workflow
Events + Webhooks
Search + Reporting
Operations

Cross-module calls go through *.Contracts only — enforced by architecture tests.

Vertical slice

One use case, one traceable loop

Platform.Catalog/ Application / Commands/ CreateCatalogItem

  • CreateCatalogItem.csCommand + Handler + generated Endpoint contract
  • CreateCatalogItemRule.csGlobal and tenant-scoped IRequestRule
  • CatalogItem.csAggregate creation and state invariants
  • CatalogPlatformTests.csUse-case behavior and regression evidence

Endpoints are generated from attributes; authorization, validation, transactions, and audit stay in pipelines so the Handler expresses the use case.

03·Architecture and decoupling

See the modules,and why they do not collapse into coupling.

The Consumer Solution is physically separated from the product repository. Product teams own business modules and Hosts; Framework and Platform provide stable capability through commercial packages. Cross-module work uses public Contracts, Ports, Integration Events, or authorized read models, while architecture tests prevent dependency drift.

System overview from entry points to runtime resources

System overview from entry points to runtime resources

Channels, Hosts, platform modules, framework services, and external resources are layered explicitly. Open the zoomable full view for detail.

Open the interactive architecture view

PACKAGE BOUNDARY

The decoupling contract between Consumer and Platform

Business code can compose platform capability without copying, modifying, or reaching through its internal implementation.

<!-- Consumer references a Profile package; Platform core source is never copied -->
<ItemGroup>
  <PackageReference
    Include="BitzOrcas.Profile.Default.Business" />
</ItemGroup>
  • ALLOW

    *.Contracts / Ports

    Synchronous calls depend only on public contracts; stores, policies, and adapter differences enter through explicit seams.

  • ASYNC

    Integration Events

    Cross-module state changes publish through the CAP Outbox, and consumers remain idempotent under at-least-once delivery.

  • DENY

    Internal / Domain / Infrastructure

    Modules may not reference internal layers, update another module’s tables, or inject a Handler as a cross-module shortcut.

Read module dependency rules
04·Implemented capabilities and adoption boundaries

Shared capabilities are implemented,and their adoption boundaries are explicit.

Authentication, authorization, caching, eventing, jobs, observability, idempotency, webhooks, multi-ORM adapters, and AI agent protocols are provided as shared building blocks. Each capability has an explicit default, extension seam, degradation behavior, failure semantics, and production acceptance boundary so business modules do not rebuild cross-cutting infrastructure.

Explore all shared building blocks
05·Platform Modules

Platform modules,optional and composable.

The product repository contains 37 Platform source boundaries covering identity, authorization, files, notifications, workflow, search, reporting, operations, legal connectors, and the support helpdesk. Consumer templates expose only modules and extensions included in supported combinations; business modules still depend only on public Contracts.

Module

Identity

Unified auth. Multiple strategies.

  • JWT bearer + refresh tokens
  • HMAC client secret + API Key
  • RBAC + ABAC + ReBAC unified decision
  • Operator impersonation with full audit trail
Explore Identity
Module

Multitenancy

Isolation by default. Cross-tenant by opt-in.

  • 8-level tenant resolver chain (claim, header, query)
  • Global query filter for tenant scoping and data isolation
  • IGlobalEntity opt-out for system-wide rows
  • Tenant-aware caching + jobs + events
Explore Multitenancy
Module

Auditing

A forensic record of every change.

  • Supported write paths enter the audit pipeline
  • Per-entity before/after snapshot
  • User, tenant, correlation ID, request path
  • 7 audit categories, sharded, Quartz cleanup
Explore Auditing
More capabilities

  • Object Storage (S3)

    Tenant-scoped object storage adapters (MinIO / S3 / Local) with uniform metadata and presigned URL semantics.

  • Async Export Center

    Asynchronous big-table paging export, progress tracking, file persistence, and multi-channel completion callbacks.

  • Full-Text Search

    Elastic / OpenSearch cross-module unified index building with authorization filtering.

  • Document Serializer

    High-concurrency document numbering engine with per-tenant date segmentation, separating rules from counters.

  • Webhook Dispatcher

    HMAC signatures, exponential backoff retries, delivery audit logging, and dead-letter queue recovery.

  • Notification Hub

    Unified user inbox with multi-channel routing pipelines across internal, email, SMS, and WeChat channels.

  • Dynamic Form Schema

    JSON Schema-driven form metadata with runtime field-level cascading validation and tenant overrides.

  • Business Tags

    Tenant-scoped universal entity tagging, hierarchical inheritance, inverted indexing, and multi-dimensional aggregation.

  • Legal Calculators

    Precise litigation court fee bracket calculations, statutory lending interest, and penalty compounding.

  • Timekeeping & Billing

    Professional matter billable hours logging, multi-rate tiers, approval workflows, and invoice staging.

  • Document Engine

    Template-driven PDF and Word document assembly for contracts, judicial filings, and compliance reports.

  • GDPR & Privacy Compliance

    PII personal data auditing, transparent field masking, export archiving, and right-to-be-forgotten erasure.

06·Under the hood

Unified stack,industry-standard choices.

Built on .NET 10, SqlSugar, EF Core, CAP, MCP, and mature OSS, with a self-built workflow engine, compile-time source generators, and architecture tests that encode team constraints. Every boundary has a concrete source and verification entry point.

  • .NET 10

    C# 14 · net10.0 LTS baseline

  • Aspire

    latest · Local orchestration

  • SqlSugar

    Core · High-throughput command engine

  • EF Core

    optional · Compliance & audit adapter

  • Dapper

    replica read · Replica read pushdown

  • CAP

    latest · Transactional outbox

  • Mediator

    sourcegen · Compile-time CQRS pipeline

  • SourceGen Mapper

    zero alloc · Zero-reflection DTO mapper

  • FusionCache

    L1/L2 · Tenant-scoped L1/L2 cache

  • Quartz

    clustered · Persistent clustered jobs

  • OpenTelemetry

    OTLP · OTLP traces, metrics & logs

  • Scalar

    OpenAPI 3.1 · OpenAPI 3.1 browser

  • ArchUnitNET

    187 tests · 187 executable architecture tests

  • MCP Server

    Agent tools · Model Context Protocol tool streaming

  • BitzOrcas.Suite

    Workbench · Desktop ER, DDL diff & review suite

  • Workflow DSL

    JSON schema · Declarative JSON state machine

07·Architecture quality gates

Architecture constraints are not conventions,they are objective gates blocking merge and release.

The authoritative merge gate covers formatting, Release compilation, domain behavior and integration tests, module boundary isolation, Consumer PackageReference verification, trim publish, Roslyn reflection checks, No T-SQL dialect validation, production deployment assets, and OpenAPI/SDK drift. Template changes independently run the 15-combination × 2-ORM generation matrix; external Commercial GA validates trusted signatures, SBOM, and production Consumer execution.

  • 26

    Test projects

    26 solution test projects cover domain invariants, Result/Error contracts, pipeline behaviors, and real SQL Server and RabbitMQ paths.

  • 187

    Architecture test files

    187 executable architecture test files enforce layering directions, module boundaries, Host purity, AOT trims, reflection rules, and persistence.

  • 15

    Supported combinations

    All 15 template combinations run deterministic generation and closure checks under both SqlSugar and EF Core; strict subsets verify private-feed builds.

  • GA

    External Commercial GA

    Authenticated feeds, trusted signatures, SBOM manifests, vulnerability policies, and external Consumer verification independently guard release.

BitzOrcas.Modern — quality gatesCI 17 merge gates
$ scripts/build/verify-all.sh
  01—04  secret · restore · format · Release build
  05—08  unit/non-Docker · Consumer Contract · XML
  09—10  architecture · integration (non-Docker)
  11—13  trim publish · reflection zero · No T-SQL
  14     production deployment and portability assets
  15     OpenAPI artifact · platform-sdk drift
  MERGE GATE  ·  15 required steps

$ scripts/build/verify-template.sh
  15 combinations × 2 ORMs — SqlSugar / EF Core
  TEMPLATE GATE  ·  run when templates or releases change

$ scripts/build/verify-commercial-ga.sh
  authenticated feed · trusted signatures · SBOM
  vulnerability/license policy · provenance · external consumer
  RELEASE GATE  ·  immutable artifacts only
Read the testing strategy
08·Who BitzOrcas is for

One template system,for .NET products at different scales.

BitzOrcas.Modern fits .NET backends that need long-term evolution, module governance, and consistent delivery evidence. The current public template ranges from a minimal single-tenant API to single- or multitenant business systems with supported platform or industry extensions.

A good fit

These product shapes can start from the template

  • Minimal APIs and integration shells

    mini-api-single provides a minimal single-tenant API closure for Consumer-owned business surfaces built on stable Framework contracts.

  • Single-tenant internal and business systems

    default-business-single generates an API and Consumer-owned Starter module, with supported coupled choices for Authorization, MasterData, or industry extensions.

  • Multitenant SaaS business systems

    default-business-multi uses authenticated tenant claims and an Aspire deployment closure while the Consumer team retains business-module source.

  • Products needing governed platform or industry extensions

    Authorization, MasterData, Finance, HR, Auction, and Legal use explicit coupled presets instead of placing unverified free-form composition in customer repositories.

Not a fit

Note if any of these apply…

  • Frontend-only projects

    BitzOrcas.Modern is a backend architecture baseline. It doesn't include frontend frameworks or UI components — pair it with your frontend stack.

  • Teams that require unrestricted combinations

    Canonical templates use a fail-closed composition matrix. The public entry accepts only registered ProfileChoice and RuntimeAdapter values rather than allowing an arbitrary closure merely to generate something first.

  • Microservices-from-day-one scenarios

    BitzOrcas is a modular monolith — modules can be extracted into services later, but it ships as one process. If you need independently deployed services on day one, plan accordingly.

  • Teams not using the .NET stack

    All architecture patterns and technology choices are based on the .NET 10 ecosystem. Non-.NET teams can reference the architectural ideas but cannot directly reuse the code.

09·Team FAQ

Before adopting the template,the team aligns on these decisions.

Clear answers about composition, extensions, isolation, persistence, and delivery gates. If an architectural decision remains open,submit an Issue

  • Q.01

    Which ProfileChoice should a new project select?

    Use mini-api-single for a minimal API. Choose default-business-single or default-business-multi for a normal business system based on tenancy. Add the coupled Authorization, MasterData, Finance, HR, Auction, or Legal suffix when that supported closure is required, then select sqlsugar or efcore separately as RuntimeAdapter. The public CLI rejects free-form combinations outside the matrix.

  • Q.02

    May a business project modify Framework or Platform source?

    No. A Consumer Solution owns its Hosts, composition manifest, configuration, tests, and business-module source. Framework and the default Platform arrive through commercial PackageReference. Product differences enter through Contracts, Store Adapters, Policies, Strategies, Options, Integration Events, or Pipeline Hooks.

  • Q.03

    Can we independently remove Hosts, Modules, Deployment, or choose another ORM?

    The public template exposes only ProfileChoice and RuntimeAdapter. ProfileChoice couples the Host, module, tenancy, and deployment closure; those parts are not free-form overrides. RuntimeAdapter selects sqlsugar or efcore. A new closure must first enter the single composition catalog and template matrix, then pass isolated-feed and Consumer Contract gates.

  • Q.04

    How should we choose single versus multi tenancy?

    Single tenancy retains the unified tenant contract with a fixed context. Multi tenancy adds resolution, lifecycle, DataScope, per-tenant cache, throttling, audit, and operations. If multiple customers share data infrastructure, start with multi and test isolation across ORM, cache, jobs, search, and administrative paths.

  • Q.05

    How do modules collaborate without tight coupling?

    Synchronous capability references only the target *.Contracts or an explicit Port. State changes publish Integration Events through the CAP Outbox. Queries use authorized Query Contracts, read models, or Reporting Marts. References to another module’s Domain, Application, Infrastructure, or internal tables are forbidden.

  • Q.06

    What are the boundaries of SqlSugar and EF Core?

    The template has 15 supported combinations. Each is verified with both SqlSugar and EF Core, producing 30 physical generation paths without increasing the template-combination count. An adapter must still preserve Store contracts, Result/Error semantics, tenant isolation, transactions, and provider parity. Dapper handles high-performance query projections from read replicas rather than acting as a standalone template RuntimeAdapter generation parameter.

  • Q.07

    Which architecture gates must run before merge?

    The authoritative entry is scripts/build/verify-all.sh. It executes 17 strict gates: secret scanning, restore, code format and unused using checks, Release build, unit/behavior tests, local PackageReference Consumer contract tests, XML docs and comments, architecture test suite, non-Docker integration tests, rate-limiting and anti-forgery stress tests, golden CLI channel validation, trim publish, Roslyn semantic reflection checks (ADR 0102/0103), No T-SQL dialect gate (ADR 0033), production deployment asset verification, and OpenAPI specification plus Platform SDK client drift checks.

  • Q.08

    Does passing repository gates mean the release is Commercial GA?

    No. Commercial GA is a separate external gate over immutable artifacts: authenticated private feed, trusted signatures, SBOM, vulnerability threshold, third-party license policy, provenance, and an external Consumer Solution. Each customer topology still proves capacity, security, recovery, and multi-replica behavior.

  • Q.09

    What are the integration and security boundaries for AI-Native MCP tools?

    BitzOrcas natively supports the Anthropic Model Context Protocol (MCP). Marking use cases or services with [GenerateMcpTool] triggers the compile-time source generator to produce JSON schemas streamed via the /mcp endpoint. When an AI agent invokes a tool, requests pass through unified authentication middleware to inject the caller’s TenantContext and SecurityPrincipal, enforcing strict DataScope rules and global tenant query filters. Agents are strictly prohibited from issuing raw SQL or bypassing aggregate boundaries; all mutations must traverse CQRS validation and audit pipelines.

  • Q.10

    How do SqlSugar, EF Core, and Dapper cooperate within the persistence layer?

    Domain and Contract layers remain 100% ORM-neutral, depending solely on ICommandRepository write ports and I*ReadStore read ports. Command write paths are driven by the chosen RuntimeAdapter (SqlSugar or EF Core), governing aggregate lifecycles, optimistic concurrency, tenant scoping, and audit interceptors; complex reporting and high-frequency read models utilize IDapperConnectionFactory to query read replicas directly, uniting clean architecture with extreme query throughput.

10·Adopt the architecture template

Choose the product shape,generate a governed Consumer Solution.

Choose a supported ProfileChoice and RuntimeAdapter. The CLI generates the Consumer Solution; the product team owns business source while Framework and Platform evolve behind stable contracts and commercial packages.

Create a project→Review GA gates
  • .NET 10 / C# 14
  • ·
  • Unified architecture