AI & Agentic Engineering Overview
As enterprise software systems transition toward being AI-Native, equipping Large Language Models (LLMs) with actionable function-calling capabilities has become a central architectural concern. Traditional solutions often rely on hand-crafted OpenAPI documents, fragile glue controllers, or direct database connections given to agents—introducing severe interface drift, duplicate business logic, absent audit trails, and multi-tenant security leaks.
BitzOrcas.Modern adopts a fundamental architectural innovation: deep native integration of the open Model Context Protocol (MCP) standard released by Anthropic, coupled with C# compile-time Roslyn Source Generators. The framework turns existing CQRS vertical slices into standard MCP Tools with zero runtime reflection overhead and zero boilerplate glue code.
1. Architectural Paradigm: Vertical Slices as Agent Tools
In BitzOrcas, developers never build redundant, specialized API controllers for AI. Every validated, tenant-aware ICommand or IQuery protected by the Mediator pipeline can be directly declared as an AI-callable tool with a single compile-time attribute:
2. Core Pillars and Design Principles
BitzOrcas AI & Agentic development is founded upon 4 primary principles:
| Core Pillar | Traditional Pitfall | BitzOrcas.Modern Solution |
|---|---|---|
| Metadata Extraction | Runtime assembly reflection scanning hurts startup performance and breaks Native AOT | Compile-Time Roslyn Generator: BitzOrcas.Mcp.SourceGenerator extracts C# XML comments and primary constructor parameters into strict JSON Schemas during compilation. |
| Execution Channel | Fragmented custom controllers or dedicated LLM RPC routes duplicate business rules | Unified Mediator Pipeline: Inbound MCP calls deserialize into real Command/Query messages, undergoing full validation, tenant context injection, and unit-of-work transactions. |
| Multi-Tenant Security | Autonomous agents risk cross-tenant data leaks and unauthorized mutation calls | Fail-Closed Dual Gate: Inbound requests require active tenant entitlement (mcpTenantAccess); the catalog dynamically hides tools when a tenant lacks the required Feature. |
| Auditability | Mutations executed by autonomous models cannot be reliably tracked back to sessions | Dedicated Audit Trail: McpToolInvocationAuditor records model session IDs, tool names, payload SHA256 hashes, duration, and execution outcomes. |
3. Section Navigation
Explore the dedicated practical chapters in this section:
Getting Started
BitzOrcas.Modern developer onboarding overview: from architectural mental models and prerequisites inspection to spinning up Docker containers and executing your first multi-tenant vertical slice.
Tutorials
The official hands-on learning roadmap for BitzOrcas.Modern. Master .NET 10 modular monolith development across 6 progressive legal-tech business scenarios.
Guides
BitzOrcas.Modern developer guides: vertical slice construction, frontend hydration, feature and module extensions, hexagonal adapters, Aspire local infrastructure, and tenant impersonation.
Building Blocks
A comprehensive overview of BitzOrcas.Modern core building blocks, spanning Unified Aggregates, QueryShape read models, CAP Outbox, multi-level caching, and S3 storage.
Cross-Cutting Concerns
Understand how BitzOrcas divides cross-cutting responsibilities among HTTP middleware, Mediator pipelines, and production adapters.
Security & Authorization
Understand BitzOrcas defense in depth across authentication, authorization, tenant isolation, request integrity, data protection, and audit.
Architecture
Explore the enterprise architecture of BitzOrcas.Modern: modular monolith boundaries, vertical slices, 10-stage execution pipeline, compile-time dual ORM, and Native AOT compilation.
Architecture Decisions
The BitzOrcas ADR index — taxonomy, lifecycle, numbering, and the selected decisions most relevant to delivery, security, operations, and modularity.
Architecture Diagrams
Visual diagram collection for the BitzOrcas.Modern system architecture.
Governance
The quality gates, production-readiness ratchets, extension intake, module governance, readiness matrix, and industry-neutral rules that make a BitzOrcas release shippable.
Platform Capabilities
BitzOrcas.Modern platform-level specialized subsystems, cross-module core engines, and rule governance center.
Business Modules
In-depth guide to BitzOrcas.Modern business module architecture, ADR 0203 physical isolation, ADR 0205 platform extension paradigms, and the Sandbox Golden Use Case.
Workflow Engine
Source-verified navigation from the visual designer and JSON DSL through deployment, runtime, tasks, notifications, history, migration, embedding, and operations.
AI & Agents
Comprehensive overview of BitzOrcas.Modern AI-Native architecture: turning enterprise vertical slices into Model Context Protocol (MCP) tools via compile-time source generation.
Frontend
The BitzOrcas frontend is a Yarn 4 monorepo. The web admin app is React 19 + Vite; the mobile shell is Taro 4 + Capacitor. Both reach the .NET backend through one typed contract.
Design Token
The frozen scope, authority order, stable themes, experience profiles, and implementation status of BitzOrcas Design System 1.2.
CLI Tools
Select Consumer Solution templates, code generation, schema, seed, workflow, and database-maintenance entries while understanding write surface, privilege, and evidence boundaries.
Testing
Understand the five-layer BitzOrcas testing system, from unit tests to commercial release evidence, and choose the right verification set for each change.
Deployment
Plan BitzOrcas deployment from local Aspire to production Hosts, configuration, databases, observability, and commercial GA.
Commercial Delivery
Understand the BitzOrcas delivery boundary from product source and NuGet packages to Consumer Solutions and formal GA.
Others
Find contribution rules, documentation maintenance, release notes, and future investment areas.
4. Related Architecture Decisions & Deep Dives
- ADR Reference: ADR 0103: Source Generators Completely Replacing Runtime Reflection
- Security Guidelines: Production Security Checklist & Sensitive Operations
- Test Verification: Inspect
tests/BitzOrcas.Framework.Tests/Mcp/for schema emission assertions - CLI Scaffolding: Use bitz generate-slice to scaffold slices annotated with
[GenerateMcpTool]