Understand the composition boundary#
Matrix supplies a modular .NET application framework. A Consumer is the application that composes it; a Product is the resulting user experience. Core means the provider-neutral kernel, not the complete application and not the CRUD engine. This distinction determines where a feature belongs and which team owns its behavior.
Domain and Application define shared contracts. Shell packages compose authorized navigation, pages and application chrome. Optional modules supply their own contracts and, where needed, provider, API and UI implementations. Dependencies point inward: the generic Shell does not depend on a concrete feature module.
| Layer | Owns | Does not automatically supply |
|---|---|---|
| Core | Stable module, resource, action, target, permission, localization and audit contracts | A business domain, database or feature runtime |
| Shell | Authorized application navigation, shared layout and page composition | A module's business behavior |
| Feature module | Its definitions, execution ports, endpoints and presentation | Unrelated application policy |
| Consumer | Domain services, persistence, adapters, identity choices, branding and deployment | A reason to change shared contracts for every local requirement |
Compose only the capabilities the application needs#
The normal host entry points are AddMatrixApi and AddMatrixWeb, paired with UseMatrixApi and UseMatrixWeb. Generated CRUD is explicit: the API adds AddCrudContext<TContext> and Web adds AddCrud. A custom application page can use ordinary Razor and protected application APIs without exposing a CRUD context.
The convenience Hosting package may still carry transitive CRUD or EF dependencies. An application with no active CRUD routes is therefore different from a package graph with no CRUD references. Module authors who require a narrow dependency graph should use the lower-level Shell packages described in the module authoring contract.
Reporting owns typed read questions and authorized exports. Dashboards compose Reporting queries within a mounted page. Wizards guide a bounded submission to an application-owned command. Preferences store permitted presentation choices. These are optional capabilities with separate ownership, not additions to a universal Core database.
Use stable contracts across API and Web#
The API produces the authorized catalog at GET /api/matrix/catalog. CRUD has additional model and presentation endpoints under /api/admin; structural metadata and effective views are separate. A module's Web page must register the same target ID as its API catalog contribution. Translated labels are display values, not identifiers.
Each CRUD context has a stable route identifier and scoped services. Equal entity names in different contexts can have different permissions. This isolates registrations; it does not implement a general tenant policy. Cross-context EF relationships are unsupported. Navigation between targets is a separate concern from a database relationship.
Choose the smallest appropriate extension#
- Identify the business operation and its authoritative service.
- Use an existing module when its execution model fits that operation.
- Add a Consumer adapter or custom page when domain rules need a different boundary.
- Package a reusable feature as a module only when its contracts no longer contain one application's assumptions.
- Keep provider-specific behavior outside Core and preserve direct endpoint authorization.
Read module composition and configuration before adding registrations. Start a new application with the implementation flow.
Check the selected release#
Architecture describes ownership; it is not a promise that every optional feature appears in every package. The capability index contains historical slice records alongside later publication evidence. Match the selected package archive, hashes and kit before adopting an API. Source candidates, published packages, Consumer acceptance and installation acceptance remain separate states.