bitzorcas
中EN

Guide

BitzOrcas developer manual

The complete entry point from first run through architecture, modules, persistence, workflows, testing, and commercial GA.

Last updated

This manual serves developers running BitzOrcas for the first time and owners making architecture, production, and commercial-delivery decisions. Current source, automated gates, and runnable examples are the evidence base. A page marked as design or not shipped does not imply an existing production feature.

Enter by outcome

Distinguish two reader environments

EnvironmentWhat you ownCorrect starting point
Product source repositoryFramework, Platform, Hosts, Tooling, and full testsframework development, source verification, and commercial package production
Consumer Solutionhost shell, composition manifest, configuration, business modules, and test sourcecreated by bitz new/template and consuming commercial capability through PackageReference

A customer project does not copy or modify Framework, Platform, Licensing Runtime, or core Generator source. Customize through Contracts, Store, Policy, Strategy, Options, Integration Event, or Pipeline Hook seams.

How the manual expresses maturity

WordingMeaning
Current implementation / sourceVerifiedchecked against current paths and symbols; environment behavior still needs tests
Design / target architecturea stated direction, not a shipped API
Degraded / Null / Unavailabledeterministic absence semantics, not production readiness
Commercial GApackage, license, adapter, operations, security, and Consumer Contract evidence all pass

When prose conflicts with source, source and automated gates win; update the page and its verify-source fact. Never invent an interface, idempotency guarantee, or reliability behavior to make a tutorial smoother.

Minimal source verification

Terminal window
# Run at the product source root.
dotnet build BitzOrcas.Modern.slnx --configuration Release
dotnet test tests/BitzOrcas.Architecture.Tests/BitzOrcas.Architecture.Tests.csproj --configuration Release

Minimal manual verification

Terminal window
# Run at the handbook root.
npm run verify:docs
npm run verify:docs-source
npm run verify:docs-depth
npm run build

One passing page is not a completed site. Final delivery also requires zero baseline pages in strict depth audit, resolvable bilingual links, renderable Mermaid and code blocks, and a successful static build and search index.

Evidence carried by a change

  1. Business outcome, failure semantics, and security boundary.
  2. Runnable examples or explicitly labeled pseudocode with domain-specific comments.
  3. A diagram only when it clarifies responsibility handoff.
  4. Applicable unit, integration, architecture, provider-parity, and consumer tests.
  5. Copyable source sweeps with expected results and documented exceptions.
  6. Unimplemented capability enters the knowledge-base architecture backlog instead of masquerading as complete.

100%

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