docs(architecture): formalize scalable extension layers, tenant/business boundaries, and service extraction criteria #739

Parent epic: #738
Related completed foundations: #679, #680, #681, #696

Context

AWCMS-Mini already has an accepted modular-monolith ADR, registry DAG checks, capability ports, and module-admission governance. The remaining gap is a single authoritative architecture decision that connects those mechanisms to the next expansion stage: many derived repositories, optional business foundations, a separate SaaS control plane, and ERP extensions.

Current documentation still needs an explicit distinction between:

• Core, System Foundation, Official Optional Business Foundation, SaaS Control Plane, ERP Extension, and Derived Application;
• tenant as security/subscription boundary versus legal entity and organization unit as business/accounting scopes;
• lifecycle dependencies versus capability dependencies;
• service catalog/subscription billing versus ERP item catalog/general ledger;
• criteria for keeping a module in the monolith versus extracting a service later.

Objective

Publish an accepted ADR and supporting diagrams/matrices that establish the target layers, ownership boundaries, dependency direction, data ownership, and evidence-based service-extraction criteria without changing runtime behavior.

Scope

• Add an ADR under docs/adr/ and update the ADR index.
• Update docs/awcms-mini/21_module_admission_governance.md, the derived-application guide, master traceability, and architecture diagrams as needed.
• Define the target layers and allowed dependency directions.
• Define tenant, legal entity, organization unit, service catalog, subscription billing, operational ledger, accounting ledger, profile/party, and business-role boundaries.
• Add a data-ownership matrix covering at least Core, workflow, reporting, event runtime, data lifecycle, integration hub, business foundation, SaaS control plane, and ERP extension.
• Formalize no shared-table write across module owners; collaboration uses a capability port, public/internal API contract, or versioned event.
• Define service-extraction criteria:
  • materially different CPU/IO/concurrency profile;
  • distinct security/process/network boundary;
  • independent deployment cadence;
  • clear operational owner/on-call responsibility;
  • separable data ownership and stable API/event contracts;
  • business-continuity need for failure isolation.
• Define future extraction prerequisites: backfill, shadow read, cutover, rollback, no-dual-write, and observability evidence.
• Map at least five derived-application examples to reusable primitives without moving their domain logic into the base.

Out of scope

• Implementing microservices, sharding, cache, tenant placement, SaaS billing, or ERP tables.
• Reclassifying existing modules without a separate admission decision and implementation issue.
• Runtime plugin installation or marketplace support.

Acceptance criteria

• One accepted ADR is the authoritative source for extension layers and boundaries.
• Dependency direction remains a DAG and is consistent with fix(modules): eliminate core module dependency cycles and add DAG validation #680/refactor(architecture): replace blog-content/news-portal circular imports with capability ports #681/docs(governance): define core, system, official optional module, and derived-app admission policy #696.
• Tenant is explicitly retained as the isolation boundary; legal entity/organization unit cannot weaken RLS.
• SaaS service catalog is explicitly separated from ERP item/product master.
• Subscription billing is explicitly separated from general ledger, AR/AP, and tenant operational accounting.
• Data ownership and no-shared-table-write rules identify the owner and allowed integration mechanism for each layer.
• Service extraction requires measurable evidence and a cutover/rollback plan; no premature microservice mandate is introduced.
• Offline/LAN-first behavior and provider-optional rules remain explicit.
• At least five derived-app examples pass the admission decision tree and remain outside the base where domain-specific.
• Internal links, Mermaid diagrams, and terminology pass bun run check:docs.
• bun run check passes with no runtime behavior change.

Documentation checklist

• ADR index.
• Module admission governance.
• Derived application guide.
• Repository architecture/master traceability.
• Glossary/data ownership matrix.
• Changeset only if required by repository policy for the affected files.