Incrementally adapt this existing application to a universal integration foundation.

GOAL
Move integration-dependent features behind stable internal identities and versioned feature contracts. Route each contract to the correct connection-specific adapter/workflow. Preserve existing behavior, data, identifiers, user access, and working connections throughout migration. Complete the authorized implementation and verification; do not stop at an architecture proposal.

Use a gradual migration: inventory the current behavior, wrap existing integration code, add compatible identity mappings, move one feature at a time, and retire old paths only after their replacements are verified.

1. Discover what exists before changing it
Read repository instructions, applicable Mock2/PRO standards, application architecture, database/schema, authentication, permissions, integrations, background jobs, observability, tests, and release process. Use current official vendor documentation when verifying actual integration capabilities. Reuse the current stack and approved dependencies; do not turn this migration into an unrelated platform upgrade.

Trace integration-related user journeys from UI/API through services/jobs to external systems and back. Identify direct vendor calls, external IDs used as local keys, namespace assumptions, embedded credentials, pagination, synchronization, writes, retries, and implicit vendor-specific behavior.

Produce a mapping table with: current feature/caller, current data identifiers, connection/source scope, observed outcome, proposed contract, existing implementation to wrap, limitations, migration risk, and validation method. Distinguish desired behavior from verified current behavior.

2. Establish the target boundaries
Use these logical components inside the existing architecture:
- Internal domain identities and scoped external identity mappings.
- A registry of specific connections/organizations, credential references, and health.
- Versioned feature contracts defining outcomes.
- Connection-specific adapters/workflows and optional feature composition.
- Capability evidence per connection and contract version.
- An authorized dispatcher and normalized result/error handling.

Keep these as application modules unless a demonstrated need justifies separate services. Do not require a visual workflow builder or new orchestration platform.

3. Preserve identifiers and backfill mappings safely
Reuse sound existing internal IDs. If a vendor ID currently serves as an internal identity, add an internal identity layer and compatibility mapping without breaking existing references or URLs.

External mapping keys must include tenant, connection, source namespace/organization, resource type, and external ID. Keep IDs as scoped strings. Preserve original external IDs and their provenance.

Keep people, patient/customer records, contacts/representatives, employees/providers, and login accounts distinct where the domain requires them. One person can have records in several systems; knowing the person does not select a unique connection or grant access.

Use additive migrations and resumable, idempotent backfills. Report collisions, ambiguous links, unmatched records, and missing source context for review. Do not merge people automatically based on names, birth dates, or email. Do not silently assign ambiguous records to a default practice. Identity links must be authorized, audited, and recoverable.

4. Define contracts around actual outcomes
Begin with a small feature catalog derived from current user journeys. A contract describes what the caller receives and what success means; the adapter describes how a system achieves it.

Specify inputs, required/optional fields, internal references, authorized scope, preconditions, side effects, filtering, pagination, ordering, time-zone/status semantics, freshness, completeness, provenance, errors, partial-result rules, and version compatibility. Do not silently weaken existing guarantees during normalization.

For example, appointments.list can return appointment basics and source references. A roster requiring names can compose it with person.summary.get. A system needing multiple demographic requests keeps that sequence inside its adapter. Do not fetch unrelated demographic information by default. Domain examples are illustrative; keep the integration core reusable outside healthcare.

5. Wrap working integrations before replacing internals
First implement adapters that delegate to the existing integration services. Preserve working credentials, synchronization checkpoints, source configuration, permissions, and event history. Move vendor-specific logic behind the boundary as each feature is migrated.

Register each practice/account/instance as its own connection. Multiple instances of the same vendor may need different configuration or capability records.

Do not disconnect and reconnect working integrations as a migration shortcut. Reauthentication is necessary only when credentials, consent, scopes, or vendor requirements actually demand it. Explain any such dependency and provide the smallest concrete connection change required.

Feature composition may reuse other contracts or private helpers. Propagate the authorized source scope, prevent cycles, bound execution, and batch/cache safely. Use existing durable jobs when recovery or asynchronous waits require them; ordinary service functions are enough for simple call sequences.

6. Record capability and execution semantics
Track verified full support, partial support, unsupported, and unverified per connection and contract version. Record restrictions, required permissions, evidence, verification date, and implementation version. Track health, enabled/configured state, and current authorization separately.

Do not infer feature parity from a vendor name, an endpoint's existence, or discovery metadata alone. An implementation must meet the contract or expose its limitation. A partial result is acceptable only under an explicit contract/caller policy.

Route using actor, tenant, connection scope, and resolved identity mappings. For multiple sources, use an explicit authorized aggregation policy. Define what 'all' means, including date/filter boundaries and pagination; expose per-source failures and overall completeness. Do not treat inaccessible or failed sources as empty successful responses. Deduplicate only with established evidence.

Apply existing and source authorization throughout. Broad service credentials do not entitle every app user to their full access. Include safe timeout/rate-limit handling, retries, write idempotency, and explicit recovery for partial multi-system writes.

7. Migrate a vertical slice and expand
Choose a low-risk read feature, such as listing appointments or contacts, as the first complete slice. Map it, wrap its current implementation, route an actual caller through the contract, and verify results. Then migrate its required compositions, other reads, and separately controlled writes.

Compare old/new read results using fixtures, captured test data, or approved read-only shadow execution. Control for changes in source data and verify identifiers, counts, filters, pagination, permissions, errors, and completeness. Never shadow-execute or duplicate production writes.

Use the existing release/feature-flag mechanism for staged cutover. Maintain a compatible old path until validation passes. Rollback must preserve new identity mappings and writes; do not make a destructive schema rollback the recovery strategy. Fallback must preserve authorization and must not bypass capability restrictions.

After a successful slice, continue through the identified in-scope features in dependency order. Mark any deferred feature explicitly and keep its current functioning route. An app with no external connections must remain usable.

8. Verify, document, and finish
Run appropriate regression and adapter-conformance checks. Cover tenant isolation, identity collisions, preserved references, mapping ambiguity, multiple connections, contract semantics, composition, partial capabilities, pagination, disconnected sources, and applicable write/retry safety.

Document the implemented architecture, migration/crosswalk table, data/backfill results, contract catalog, per-connection capability matrix, cutover/rollback procedure, and how a second vendor adapter can be added. Reuse existing audit/Relay tracing when present, with correlation IDs and contract/source/version evidence. Keep credentials and sensitive payloads out of routine logs.

Report exactly which callers/features now use the foundation, which still use existing paths, what was tested, any required reconnection, unresolved mapping issues, and remaining limitations. Follow the project's authorized review and release process. Do not claim completion for unverified adapters or silently abandon unmigrated in-scope behavior.