# Design Docs

## Platform target architecture

- [`engineering-verification-workflow.md`](engineering-verification-workflow.md)
  — scoped local verification, CI/environment proof, batched tests and durable
  performance evidence; detailed procedures linked from the root agent guide.

- [`configuration-and-execution-lifecycle.md`](configuration-and-execution-lifecycle.md)
  — normative ownership and lifecycle contract for application installation,
  online configuration, requests and durable work; version meanings, recorded
  coupling inventory and required consumer-cutover proof.

- [L1 MCP Worker contract](https://github.com/pingcap-inc/nexuscrm-app-packs/blob/49e9998af867edfc3f5715eee2bfc8e8e0b8c2f7/docs/design/mcp-l1-worker.md)
  — current independent L1 MCP module and user-permission contract. The Core
  [ownership pointer](mcp-multi-agent-interoperability.md) records supersession;
  Core no longer owns MCP HTTP/tool or Connected App onboarding semantics.
- [`browser-programmatic-auth-context-split.md`](browser-programmatic-auth-context-split.md)
  — historical monolith browser-session, programmatic API, Connected App,
  migration, and rollback proposal for issues #1123, #1865, and #1867.
- [`metadata-authoring-current-paths.md`](metadata-authoring-current-paths.md)
  — current Runtime/setup ownership, retired monolith routing, remaining
  authoring gaps, and the next schema-consumer proof for #4694.
- [`flow-runtime-v2-execution-architecture.md`](flow-runtime-v2-execution-architecture.md)
  — compiled execution profiles, durable state ownership, transaction and retry
  protocol, scheduler migration, and release acceptance for issue #4001.
- [`layout-authoring-runtime-domain.md`](layout-authoring-runtime-domain.md)
  — synchronous tenant Layout ownership in Runtime storage, current page
  resolution, and the hard boundary from Catalog publication.
- [`nexuscrm-serviceification-target-architecture.md`](nexuscrm-serviceification-target-architecture.md)
  — target service boundaries, metadata-driven App contract, consistency and
  version semantics, measurable DoD, and pre-implementation ADR gates. Its
  serviceification direction passed two independent architecture reviews.
  Dated delivery status is historical; current owners and retirement boundaries
  are indexed in `metadata-authoring-current-paths.md` and capability ADRs.
- [`runtime-trusted-delegation-contract.md`](runtime-trusted-delegation-contract.md)
  — P6 authority, delegation, AppInstallation, epoch/lease, failure, and
  executable isolation contract for Runtime security admission; P6-D retains
  the explicitly deferred numeric security decisions.
- [`issue-3725-integration-work-effect-ownership.md`](issue-3725-integration-work-effect-ownership.md)
  — Integration durable-work, external-effect, principal-generation,
  retry/repair, migration, and Outreach pilot ownership contract. It owns the
  target distributed scheduler decision used by the connector-root contract.

Design documents in this directory are not all current-state repository maps.
Many are issue-specific PRDs or dated design notes that preserve the file paths
that were true when the issue was designed.

Normative authority is routed by fact and specificity. The target architecture
owns service boundaries and cross-capability invariants. When it links a
capability ADR as the owner of an exact field inventory or state machine, the
target architecture and consumer ADRs must reference that owner rather than
copying the fact. Introducing the specialized owner is an atomic
source-of-truth cutover: add the owner, switch every normative read path, and
delete the superseded inline copies in the same PR.

When a design doc cites deleted frontend roots such as
`frontend/src/features/**`, `frontend/src/components/**`,
`frontend/src/core/**`, or `frontend/src/infrastructure/**`, treat the citation
as historical context unless the document explicitly says it has been refreshed
after the final frontend relocation seal. The current frontend ownership map is
[`frontend-l0-l1-ownership-inventory.md`](frontend-l0-l1-ownership-inventory.md).