Integration Framework Specification

1. Purpose

This document defines the Tov+ integration framework for external systems and partner connectivity.

It establishes:

• what an integration is in Tov+
• how integration principals are represented
• how scopes and permissions work for external systems
• how integrations are configured and connected
• how APIs and webhooks are used by integrations
• what security and operational rules govern integrations

This is the main reference for implementing the integration layer later.

2. What an integration is

An integration is a Tov+ interface-layer connection between the platform and an external system, represented as a scoped external principal plus configuration, credentials, and adapter behavior.

An integration is not:

• a top-level business domain
• a human vendor user
• a vendor actor
• a hidden bypass around permissions

Differentiate these clearly:

Vendor actor

An occasion-scoped actor in the business graph representing a vendor organization, vendor contact, or vendor team.

Human vendor user

A human authenticated user_principal linked to a vendor actor and granted scoped access to Tov+ surfaces.

Integration principal

A non-human external principal authenticated with machine credentials and scoped through explicit integration grants.

Partner company

A real-world business entity such as a printer, venue, or caterer. It may be represented in Tov+ by:

• vendor actors for human collaboration
• integration records for system-to-system access
• or both, if the partner has both humans and software connections

Service provider

An external platform or infrastructure service used by Tov+ such as messaging, storage, or maps. Service providers may be modeled as platform integrations even when they are not planner-facing partners.

3. Integration categories

Tov+ should classify integrations along two axes: business role and interaction pattern.

3.1 Business-role categories

Partner integrations

Used by external partner organizations interacting with occasion/business data.

Examples:

• printing companies
• venues/halls
• caterers

Platform integrations

Used by Tov+ to communicate with infrastructure or platform services.

Examples:

• messaging providers
• storage/media providers
• map/travel services
• calendar providers

3.2 Interaction-pattern categories

Inbound integrations

External systems send data or events into Tov+.

Examples:

• partner webhook updates
• poll/import sync from a provider API

Outbound integrations

Tov+ sends data or events outward.

Examples:

• webhook delivery
• pushing print package data
• notifying a caterer system

Sync-based integrations

State is exchanged through polling, batch sync, or explicit reconciliation jobs.

Event-driven integrations

State is exchanged through webhooks or event-triggered API calls.

3.3 Category composition rule

An integration may belong to multiple categories simultaneously.

Examples:

• printer integration: partner + outbound + event-driven
• calendar provider: platform + outbound + sync-based
• venue webhook receiver: partner + inbound + event-driven

4. Principal and credential model

4.1 Integration principal model

Every integration acts as an integration_principal.

The principal is backed by:

• an integration_app record
• one or more active credentials
• explicit scope grants
• environment metadata

4.2 Identity model

An integration identity should include:

• stable integration id
• display name
• category
• owning organization or partner reference if relevant
• environment (development, staging, production)
• status (active, disabled, revoked, archived)

4.3 Credential model

Recommended first-phase credential model:

• key id
• secret material stored as hash or encrypted server-side value
• rotation metadata
• revocation metadata

Optional derived pattern:

• short-lived signed access token minted from key/secret authentication

4.4 Rotation and revocation

Requirements:

• secrets must be rotatable
• credentials must be revocable independently of the integration record
• usage must be auditable per credential
• disabled or revoked credentials must stop future access promptly

4.5 Environment separation

Environment separation is mandatory.

Rules:

• production credentials never access staging or development data
• staging/test integrations must not receive production webhook traffic
• environment is part of integration identity and webhook configuration

5. Scope and access model

5.1 Core rule

Integrations are scoped external principals. They never inherit human planner/admin access.

5.2 Supported scope levels

Integration scopes may be granted at:

• platform scope for infrastructure/platform services
• occasion scope
• event scope
• module installation scope
• module enablement scope
• resource scope

5.3 Action restrictions

Integrations must be scoped by both resource and action.

Examples:

• printer can read published invitation package artifacts
• venue can read seating plan outputs for one event
• caterer can read meal counts and dietary summaries but not unrelated guest notes
• messaging provider may send through communications delivery contracts without reading arbitrary guest content

5.4 Access to shared domains

Integrations may access:

• assets only when asset access is explicitly granted or when a published artifact is meant for them
• communications-derived data only when the integration’s purpose requires it and privacy permits it

They must not access:

• unrelated communications threads
• raw guest/private planner notes without explicit need and grant
• module-internal data outside granted scope

5.5 Difference from vendor access

Vendor access:

• is human
• uses user_principal
• resolves through linked vendor actor

Integration access:

• is non-human
• uses integration_principal
• resolves through machine credential plus explicit scope grants

Rule:

• do not collapse vendor users and integrations into one “partner” auth model

6. Configuration and lifecycle model

6.1 Connection model

An integration connection should include:

• integration app record
• enabled/disabled state
• environment
• credential set
• scope grants
• adapter configuration
• webhook subscription configuration if applicable

Connection rule:

• platform integrations may exist once at platform scope and then be referenced by many occasions
• partner integrations should usually be installed or connected per occasion, even if the same partner organization exists across many occasions

6.2 Configuration layers

Recommended layers:

• platform integration definition metadata
• installation/connection record
• occasion-level configuration
• event-level scoping where required
• adapter mapping configuration

6.3 Secrets handling

Secrets must:

• never be stored in plaintext where avoidable
• be rotatable
• be redacted from ordinary logs and support UI
• be separate from business configuration payloads

6.4 Mapping and transforms

Mapping configuration may include:

• field mapping rules
• template selection
• payload transformation settings
• destination identifiers

Rule:

• mappings belong to integration configuration, not to core domain tables

6.5 Lifecycle states

Recommended lifecycle:

1. defined
2. configured
3. enabled
4. active
5. disabled
6. revoked or archived

7. API and webhook interaction model

7.1 When integrations call APIs

Integrations call APIs when they need:

• pull access to scoped state
• explicit mutation with auditable request/response semantics
• sync/reconciliation operations

Examples:

• printer fetches published artifact metadata
• caterer fetches meal summary data
• calendar integration pulls event schedules

7.2 When integrations receive webhooks

Integrations receive webhooks when:

• Tov+ should push meaningful business events asynchronously
• partner workflows benefit from event-driven updates

Examples:

• printable.generated
• seating_plan.published
• rsvp.submitted

7.3 Adapter responsibility

Adapters perform:

• translation between Tov+ canonical models and partner/provider payloads
• signing/authentication
• provider-specific error classification
• replay-safe serialization logic

Adapters must not:

• redefine permissions
• bypass application service orchestration

7.4 Retry and failure handling

API-call-based integrations and webhook delivery should both support:

• retry for transient errors
• idempotency/deduplication
• durable delivery/sync records
• operator-visible failure states

8. Security model

8.1 Least privilege

Every integration must receive the smallest scope that satisfies its business purpose.

8.2 Tenant isolation

Integrations must not cross occasion boundaries without explicit grants.

8.3 Signature and verification

Rules:

• outbound webhooks are signed
• inbound partner webhooks require signature or shared-secret verification
• replay-resistant timestamp handling is recommended

8.4 Access review and expiration

Recommended requirements:

• integrations should support periodic access review
• temporary partner integrations may have explicit expiration dates
• stale or unused credentials should be candidates for revocation

9. Operational model

9.1 Auditability

Audit records should capture:

• integration id
• credential id
• action/resource/scope
• request or delivery id
• outcome

9.2 Health and status

Each integration should expose operational state such as:

• active
• degraded
• failing
• revoked

9.3 Failed sync handling

Failures should be:

• recorded durably
• classified as retryable or terminal
• replayable or manually recoverable where practical

9.4 Alerting and support

Operational expectations:

• repeated failures should surface alerts/metrics
• support/debugging should have correlation ids and delivery/sync history
• secret material must remain redacted

10. Worked example summary

The framework must cleanly support:

• printers with access to published invitation/printable outputs only
• venues with access to event seating/layout outputs and selected timeline/operations data
• caterers with access to meal counts and dietary summaries without general guest visibility

These examples are expanded in the worked-example document.

11. Anti-patterns

• treating integrations as trusted superusers
• mixing human vendor access and machine integration access into one model
• partner-specific custom endpoints that bypass central APIs and permissions
• storing secrets in plain config blobs
• adapter logic duplicated separately in controllers, jobs, and random modules
• exposing more guest or planner data than the integration purpose requires
• environment mixing between staging and production credentials

12. Final summary

Tov+ integrations are scoped interface-layer connections represented as external principals with explicit credentials, scopes, adapter configuration, and operational state. They are distinct from human vendors, do not bypass permissions, and interact through stable APIs and webhooks with durable audit, retry, and observability expectations.