Connector Platform — Marvia Kernel

Marvia-14

One integration layer. No provider logic outside an adapter.

Every third-party service reaches Marvia through the connector platform: workspace-owned credentials, permission-checked operations, queue-driven syncs and a normalized envelope that hides the provider entirely.

Manifest version

1.0.0

Provider agnostic

No provider-specific logic outside an adapter.

Workspace scoped

Connectors belong to workspaces; credentials are workspace-owned.

Permission aware

Role-based access on every connector operation.

Rate limit safe

Queue-driven syncs with backpressure handling.

Manual refresh first

User-initiated syncs outrank scheduled ones.

Strong typing

Schema-driven normalization for every payload.

Versioned

Explicit versioning for connectors and normalized data.

Extensible

An SDK for custom connectors and capabilities.

Manifest

Sixteen declared fields, validated before authorization

Scopes, permissions and rate limits are declared up front and shown to the workspace owner.

Required fields

id: Unique, stable identifier; never reused after deletion.
name: Human-readable name shown in the connector gallery.
slug: URL-friendly identifier used in routes and docs.
category: One of the registered connector categories.
provider: Official provider name, exactly as the provider spells it.
version: Semantic version of the connector, not of the provider API.
scopes: OAuth2 scopes requested, shown to the owner before authorization.
permissions: Workspace permissions required, e.g. connector.read.
capabilities: Supported features such as sync, webhook or backfill.
authentication: One authentication kind from the framework.
syncStrategy: Incremental, full or webhook.
rateLimits: Provider-specific limits the sync engine must respect.
documentation: Link to provider documentation.
homepage: Official provider page.
support: Support channel for connection failures.
license: License type of the connector implementation.

Example manifest

{
  "manifestVersion": "1.0.0",
  "id": "google-search-console",
  "name": "Google Search Console",
  "slug": "google-search-console",
  "category": "search",
  "provider": "Google",
  "version": "1.0.0",
  "scopes": ["https://www.googleapis.com/auth/webmasters.readonly"],
  "permissions": ["connector.read", "connector.sync"],
  "capabilities": ["connector.gsc", "sync", "webhook"],
  "authentication": "oauth2",
  "syncStrategy": "incremental",
  "rateLimits": { "requestsPerMinute": 600, "dailyQuota": 200000, "concurrency": 4 },
  "documentation": "https://developers.google.com/webmaster-tools",
  "homepage": "https://search.google.com/search-console",
  "support": "https://docs.marvia.dev/connectors/google-search-console",
  "license": "MIT"
}

Rules

Every third-party integration ships a manifest; there is no unregistered connector.
Scopes and permissions are shown to the workspace owner before authorization.
Rate limits are declared, not discovered by hitting the provider wall.
A manifest change that adds a scope requires re-authorization.

Credentials are workspace-owned and never readable

Connectors receive a secret reference; the vault performs the authorized call on their behalf.

Framework

oauth2 · supported: Preferred for user-authorized provider access.
api-key · supported: Static provider credentials issued to the workspace.
byok · supported: Bring your own key for AI and paid providers.
token · supported: Short-lived credentials refreshed before expiry.
webhook-secret · supported: Signature verification for event-driven syncs.
manual-credentials · supported: User-provided credentials for self-hosted providers.
service-account · planned: Machine identity for organization-wide access.

Secrets

No plaintext secret ever enters code, config, logs or a snapshot.
Connectors receive a secret reference; the vault performs the authorized call.
Rotation and revocation happen in the vault and take effect immediately.
BYOK keys are workspace-owned and deletable on request.

Workspace binding

Workspace: Credentials, connectors and every approval decision.
Connector: Provider adapter, sync state, cursor and health.
Project: Consumption of a connection; usage stays isolated.

Lifecycle & health

Ten phases, one validated state machine

Health is a first-class state; an expired credential pauses sync instead of failing silently.

Create

Initialize a connector instance inside the workspace.

Authorize

Validate credentials through OAuth2 or an API key.

Validate

Check provider health, scopes and effective permissions.

Sync

Fetch, normalize, validate and store provider data.

Refresh

Apply incremental updates from the stored cursor.

Pause

Temporarily disable sync without losing credentials.

Reconnect

Reauthorize after an expiry or a revoked grant.

Revoke

Revoke credentials with the provider and the vault.

Delete

Remove the connector and every derived record.

Health check

Monitor provider status and surface state changes.

Health states

connected: Active and healthy.
disconnected: Credentials invalid or revoked.
warning: Rate-limited or partial failures.
expired: Credentials expired and need reauthorization.
rate-limited: Provider is throttling requests.
error: Critical failure; sync is halted.
pending: Initial setup not completed.

Governance

Breaking changes ship a new connector major version with a migration guide.
Deprecation is announced six months before removal.
Health thresholds alert the workspace on error and expired states.
Every failure mode has a runbook with recovery steps.

TLS 1.3 in transit, AES-256 at rest for every credential and payload.
Every connector operation writes an immutable audit log entry.
PII retention follows GDPR/CCPA: 30 days unless the workspace shortens it.
Security review is required before a new connector is approved.

Sync engine

Manual refresh first, automation through the queue

Rate limits are respected by design; failures retry with exponential backoff and alert the owner.

Modes

Manual sync · supported: User-initiated from the dashboard or context dock.
Webhook sync · supported: Provider event with a verified signature.
Incremental sync · supported: Delta from the stored cursor.
Full sync · supported: Complete refresh, owner-initiated.
Scheduled sync · planned: Cron-driven, queued at low priority.

Pipeline

01AuthenticateA vault-resolved authorized client.
02FetchRaw provider payloads inside the rate-limit budget.
03NormalizeSchema-compliant normalized objects.
04ValidateSchema validation results; invalid batches are rejected.
05StorePersisted records scoped to the workspace.
06Knowledge objectsNodes and edges merged into the knowledge graph.
07EventsLifecycle events on the kernel bus.
08DashboardUpdated widgets, status and warnings.

Retry policy

max attempts 5base 1000msceiling 300000msjitter on

A manual sync always outranks a scheduled one in the queue.
Rate-limit responses pause the connector instead of retrying immediately.
Failures retry with exponential backoff and alert the owner after the last attempt.
Backpressure prioritizes critical connectors and defers background work.

Runtime responsibilities

Resolve credentials through the vault and inject an authorized client.
Enforce connector permissions before any provider call is made.
Respect declared rate limits and apply backpressure through the queue.
Validate normalized data against its schema before storage.
Emit lifecycle events and update health state on every transition.
Write an immutable audit entry for every connector operation.

Normalization

Extensions never see a provider payload

Every connector returns the same envelope, schema-validated before storage.

Envelope

{
  "normalized_objects": [
    { "type": "query", "query": "marvia seo", "clicks": 128, "impressions": 3420, "position": 4.2 }
  ],
  "raw_payload": { "rows": [] },
  "metadata": {
    "version": "1.0.0",
    "sync_time": "2026-08-05T02:00:00.000Z",
    "provider": "Google"
  }
}

Rules

Every connector returns the same envelope: normalized objects, optional raw payload, metadata.
Normalized data is schema-validated before it is stored.
Raw payloads are retained only when the workspace enables debug mode.
Normalized objects feed knowledge objects and then the universal website object.

Permissions & capabilities

Role-scoped access, capability-based discovery

Extensions consume a connector capability name; they never reach a provider SDK.

Permissions

connector.read: View connector data and sync history.
connector.write: Modify connector settings and mappings.
connector.sync: Trigger manual and full syncs.
connector.admin: Full access, including lifecycle transitions.
connector.secrets: Manage credentials through the vault.
workspace.connectors: Add and remove connectors in the workspace.

A workspace owns credentials; projects only consume connections.
connector.secrets is separable from connector.admin for least privilege.
A permission check failure fails closed before any provider call.
Every grant and revocation is written to the audit log.

Capability registry

connector.gscconnector.ga4connector.google_adsconnector.meta_adsconnector.telegramconnector.paymentconnector.storageconnector.aiconnector.cmsconnector.github

Extensions consume a connector capability name, never a provider SDK.
Two connectors may implement one capability; the runtime resolves them.
Removing a connector removes every artifact and cursor it registered.

SDK, surfaces & testing

Seven functions to build a connector

The dashboard, context dock and documentation are generated from the same manifest.

SDK surface

defineConnector(manifest): Register connector metadata and validate the manifest.
defineProvider(adapter): Implement the provider adapter contract.
defineAuth(flow): Declare the authentication flow and required scopes.
defineSync(strategy): Implement incremental, full or webhook synchronization.
defineCapability(name): Declare a supported feature other code can discover.
defineWebhook(handler): Verify signatures and handle provider events.
defineHealth(check): Report provider availability and connection health.

Dashboard widgets

Connected services: Every active connector with its provider and category.
Sync status: Last sync time, item counts and health state.
Warnings: Rate limits, partial failures and expiring credentials.
Quick actions: Refresh, pause and reconnect without leaving the dashboard.

Context dock

Provider nameStatusLast sync timeHealth stateRefresh actionConnected workspace

Mandatory tests

Authentication test: Credentials and scopes are accepted by the provider.
Health check: Provider availability and latency budget.
Sync validation: Normalization produces the expected objects.
Schema validation: Normalized data matches the registered schema.
Rate limit simulation: Backpressure and retry behaviour under throttling.

Tooling & documentation

Automated connector tests in CI/CD.
Debug mode with logs and traces per connector.
Sandbox environment isolated from production data.

Configuration guideScopes and permissionsExample implementationTroubleshootingAPI referenceChangelog

Coding standards

Provider agnostic: no provider-specific logic outside an adapter.
Strong typing: every payload is schema-driven.
Queue first: manual syncs are prioritized, automation is queued.
No duplicated adapters: reuse the adapter across connectors of one provider.
Versioned: connectors and normalized data both carry explicit versions.