The Developer Guides provide day-to-day practical manuals for building robust applications on BitzOrcas.Modern. They cover standardized patterns ranging from single-file vertical slices and frontend metadata hydration to hexagonal adapters, Aspire local orchestration, and operator impersonation sandboxes.
Guides Roadmap
Hands-on Guides Matrix
| Guide & Link | Core Problem Solved | Target Audience |
|---|---|---|
| 1. How to Write a Command Slice | ”One Use Case, One File” standard, 10-tier pipeline, and ICommandRepository | Backend / All Engineers |
| 2. Frontend Integration & Hydration | OpenAPI SDK synchronization, IReadModelMetaMapped, and Stage 10 hydration | Full-Stack / Frontend |
| 3. Add a Dashboard Page | React 19 + TanStack Query dashboard, @bitz/widgets, and RBAC action gates | Frontend Engineers |
| 4. Add a Feature to an Existing Module | Extending aggregate invariants, vertical slices, and Testcontainers integration tests | Backend Engineers |
| 5. Add an Autonomous Business Module | Three-tier .csproj layout, IAppModule governance, and ArchUnit test gates | Core Engineers / Architects |
| 6. Implement Hexagonal Adapters | Inverted narrow ports, Polly network retries, and fallback test mocks | Backend Engineers |
| 7. Local Infrastructure Orchestration | .NET Aspire AppHost for SQL Server, Redis, RabbitMQ, and data persistence | All Engineers / DevOps |
| 8. Operator Impersonation Sandbox | Short-lived JWT impersonation, dual-identity audit trails, and read-only sandboxes | DevOps / Security |
| 9. Declarative Seed Data Provisioning | Module-level ISeedDataContributor and idempotent master data seeding | Backend / Deployment |
| 10. Framework Upgrading Guide | .NET 10 upgrade strategy, Roslyn cache maintenance, and zero-downtime DB migrations | Architects / DevOps |
| 11. Integrate Global Search & Indexing | Same-transaction indexing events, authoritative rebuild sources, and full-text search | Backend / Architects |
| 12. CLI Dual-Track NuGet Distribution | Public NuGet.org vs. private Yunxiao feeds, packageSourceMapping, and CI/CD pipelines | Platform / DevOps |
Chapter Navigation
- 01/15
Practical Guide: How to Write a Command Slice
Build an enterprise command slice following the One Use Case One File standard: Minimal API route metadata, declarative RBAC permissions, IRequestRule pure validation, ICommandRepository persistence, and aggregate invariant enforcement.
- 02/15
Practical Guide: Frontend Integration & Metadata Hydration
Master frontend integration in BitzOrcas.Modern: OpenAPI TypeScript SDK generation, IReadModelMetaMapped projection, 10-stage pipeline Stage 10 dictionary and entity hydration, and React 19 best practices.
- 03/15
Practical Guide: Add a Feature to an Existing Module
Master the 5-step feature delivery pipeline in BitzOrcas.Modern: extending domain aggregate invariants, single-file vertical slice, declarative RBAC endpoints, ICommandRepository persistence, and Testcontainers validation.
- 04/15
Practical Guide: Add an Autonomous Business Module
Master creating autonomous modular monolith sub-domains in BitzOrcas.Modern: Contracts/Domain/Application project segregation, TenantAggregateRoot domain models, IAppModule governance metadata, and ArchUnit architecture guardrails.
- 05/15
Practical Guide: Implement Hexagonal Infrastructure Adapters
Master Hexagonal Ports and Adapters in BitzOrcas.Modern: define domain ports, implement production infrastructure adapters, encapsulate third-party network errors, configure Polly resilience, and register fallback mocks.
- 06/15
Practical Guide: Add a Dashboard Management Page (React 19)
Master building enterprise management dashboard pages in BitzOrcas.Modern React 19 + TanStack Query: route registration, OpenAPI SDK generation, metadata table hydration, and RBAC permission gates.
- 07/15
Practical Guide: Local Infrastructure & .NET Aspire Orchestration
Master local development orchestration in BitzOrcas.Modern: .NET Aspire AppHost, SQL Server 2022, Redis 7, MinIO containers, verified port matrices, volume persistence, and database schema reset.
- 08/15
Practical Guide: Operator Impersonation & Security Audit
Master operator impersonation in BitzOrcas.Modern: short-lived dual-identity JWTs, DelegatedSessionRestrictionPipelineBehavior sensitive operation blocks, and immutable dual-identity audits.
- 09/15
Practical Guide: Declarative Seed Data & Idempotent Initialization
Master seed data provisioning in BitzOrcas.Modern: implementing the ISeedStep contract, multi-tier environment gates (Global / Tenant / Demo / ProductionSafe), DAG topological dependency ordering, and automated idempotent seeding via --init-schema.
- 10/15
Practical Guide: Framework Upgrades & Breaking Change Migration
Smooth upgrade guide for BitzOrcas.Modern: central package management version locking (CPM), Roslyn generator cache maintenance, database schema migrations, frontend dependency alignment, and quality gate validation.
- 11/15
Guide: Dual-Track NuGet Distribution & Release Management for Bitz CLI
Comprehensive operational guide for Bitz CLI packaging and distribution: public NuGet.org vs. enterprise Yunxiao private feeds, packageSourceMapping supply chain defense, local offline validation, and CI/CD automation.
- 12/15
Tutorial: Integrating a Module with Global Search and Index Governance
Complete walkthrough for wiring a business module into BitzOrcas.Modern global search: same-transaction incremental index events, an authoritative rebuild source, host source-catalog configuration, authoritative hit re-checks, architecture-test locks, and end-to-end verification.
- 13/15
EF Core Isomorphic Integration & Interceptor Guide
Practical guide: configuring and utilizing EF Core in BitzOrcas.Modern, exploring Audit interceptors, PII encryption, global query filters, and CAP outbox integration.
- 14/15
Dapper Read-Side Performance & Connection Pooling
Practical guide: leveraging Dapper and read-only connection pooling in BitzOrcas.Modern to maximize throughput for analytical dashboards, reporting, and high-concurrency pagination.
- 15/15
Ten Architecture Anti-Patterns & Operational Pitfalls
Senior architect guide to avoiding production catastrophes: dissecting async deadlocks, module layer leaks, tenant isolation breaches, and unverified AI mutation loops.