--- id: CON-PFM-INT-001 name: Integration feature: FEAT-PFM-INT-01 product_area: platform module: integrations revision: 1 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- An integration is a versioned provider offering in Rhythm’s catalogue, together with a workspace installation recording its adopted settings and accepted access. owned_by: MOD-PFM-INT synonyms: - Connector - Provider - Deployed adapter not_to_be_confused_with: - Provider account link - Customer-defined customization handler - Provider-independent operation contract facets: - name: Catalog entry meaning: 'Rhythm’s provider description includes identity, presentation, categories and customer availability.' used_for: Helping staff recognize an eligible offer. - name: Version and release notes meaning: >- A release carries its immutable published manifest and associated release notes through its version lifecycle. used_for: Keeping account behaviour stable while preparing upgrades. - name: Capabilities and features meaning: Contract majors describe supported provider jobs and their optional implementation features. used_for: Explaining the offer and checking whether it can serve a request. - name: Deployment meaning: 'Deployment identifies running code for a release in an environment, with active and draining instances.' used_for: Locating the adapter that receives calls. - name: Availability meaning: 'Public, named-customer and internal audiences govern catalogue visibility.' used_for: Offering providers to the intended customers. - name: Installation meaning: >- A workspace adoption record retains enabled, suspended or uninstalled standing and its suspension reason. used_for: Pausing or ending workspace use without losing the adoption record. - name: Accepted access meaning: >- The saved selection of capabilities, events, data scopes and Rhythm permissions stays within the current declaration. used_for: 'Checking supported consent boundaries during calls, leases, subscriptions and authorization.' - name: Installation settings meaning: Provider-declared configuration values belong to the workspace’s installation. used_for: Supplying customer-specific provider settings. - name: Platform secret meaning: An account owned by Rhythm uses a staff-written secret whose value is not returned. used_for: Authenticating integrations that operate through Rhythm’s provider account. relationships: - to: CON-PFM-INT-002 statement: 'A workspace installation groups its provider connections, each using a pinned release.' provenance: observed source: 'services-platform:modules/integrations/db/integration-connections.table.ts:installation_id' - to: CON-PFM-INT-003 statement: Gateway calls use supported capabilities within the installation’s accepted access. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/consent-narrowing.integration.spec.js#INT-ACC-0509 step 4: refuses the refund 409 binding_ineligible - to: CON-PFM-INT-004 statement: >- Release declarations identify produced and subscribed events, and subscriptions check the accepted selection. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/subscriptions/subscription-consent.integration.spec.js#is refused although the manifest declares it, naming the field and the type lifecycle: - state: internal meaning: The definition is registered without a customer offer. how_it_changes: Staff choose its audience. - state: offered meaning: An eligible customer can discover a published offer. how_it_changes: Publication and audience changes alter the offer. - state: installed meaning: A workspace has adopted settings and access. how_it_changes: Its administrator manages installation standing. acted_on_by: - CAP-PFM-INT-001 - CAP-PFM-INT-002 - CAP-PFM-INT-003 - CAP-PFM-INT-004 - CAP-PFM-INT-014 visible_to: - ACT-PFM-017 - ACT-PFM-018 - ACT-PFM-019 - ACT-PFM-021 evidence: - >- services-platform source inventory: modules/integrations/db (integration-definitions, integration-versions, capability-definitions, integration-capabilities, integration-deployments, integration-availability-grants, integration-installations tables), services/catalog/catalog.ts, services/installations/installation-lifecycle.ts, services/registration/register-integration-version.ts; docs/integrations/README.md; docs/milestones/INTG-M1-*. - 'macroservice-libraries source inventory: packages/integration-contracts (manifest, capabilities).' - >- react-console source inventory: components/integrations/catalog-screen.tsx, provider-detail.tsx, installation-detail.tsx. supersedes: [] --- # Integration ## What It Is An integration gives staff a reusable provider offering within Rhythm. It may offer payment operations, virtual meetings or another external service. The catalogue describes the offering and the releases available for it. A workspace adopts that offering through an installation, which retains the administrator’s settings and access choices. Provider account connections then belong beneath that installation. The adapter is the running software that carries out provider work. Its release declaration describes capabilities, authentication and configuration. This is useful to a product manager because it separates three decisions: whether the provider implementation exists, whether Rhythm offers it to this customer, and whether this workspace adopts it. Those decisions can occur at different times and have different responsible actors. A published description also gives account connections a stable reference while later releases are prepared. ## What It Is Not The offering is distinct from the provider account used by the customer. Installing a payment integration does not identify the account that receives a payment. It also does not select which account should serve a business unit; that selection belongs to routing configuration. A provider capability describes the job available across implementations, while an extension supplies customized application behaviour. ## How It Is Used Rhythm staff maintain releases and customer availability. Administrators browse eligible offers, review provider detail and establish the workspace installation. They return to its settings when the customer’s requirements change or use suspension while investigating a problem. Readers inspect the saved records without performing those changes. A sound review distinguishes requested access from accepted access and asks which account connections will be needed. The current code permits restored acceptance within the declaration, although the recorded narrow-only decision does not settle that behaviour. An installation that still has connected accounts requires further work before removal. Those questions belong to adoption and account lifecycle rather than to choosing an attractive catalogue tile. ## Its Facets **Catalogue and availability.** Presentation information identifies the provider and helps staff find it. Availability determines the customers to whom Rhythm offers it. **Releases and capabilities.** Versioned declarations describe supported jobs and optional features. Release notes give context for a change, while pinned account connections retain the implementation they use. **Deployment.** The running location connects a release description to executable adapter code. Replacement deployment and replacement release are separate operations. **Installation and accepted access.** The workspace adoption records its standing and choices. Stored consent is checked on supported call and event paths; the deferred data-grant service does not establish general enforcement of data scopes. **Settings and platform secrets.** Installation settings configure provider behaviour for the customer. Accounts held by Rhythm instead use secrets administered by Rhythm staff, without returning the stored values. ## How It Relates Connections supply the provider accounts for an installation. Capability calls use those accounts for provider work. Integration events carry notifications back to applications and subscribed changes out to providers. The workspace lifecycle owns deletion of the workspace itself; this module participates by removing its provider records. ## What It Could Become The product should settle whether acceptance can be restored after withdrawal and whether removal should permanently discard subscriptions. Staff catalogue screens remain later work. A future offer may need clearer support information or additional providers, but neither an observed release nor a registered adapter establishes product acceptance. Future adoption flows should continue to expose the difference between an available implementation and an approved customer offering.