Architecture Principles

SiteKit creates reliable interfaces to private web apps. It does not own downstream business workflows.

SiteKit's product boundary is deliberately narrow:

private website -> reviewed adapter -> typed clients + MCP tools

SiteKit discovers and maintains the data interface layer for websites that do not expose useful public APIs. It does not decide how two systems reconcile, which system wins a business conflict, or when a workflow should run.

What SiteKit Owns

SiteKit owns:

Browser capture and autonomous discovery.
Auth lifecycle and session handling.
Adapter IR and generated clients.
MCP tools generated from verified operations.
Request validation, retries, rate limits, and drift detection.
Adapter repair and versioned releases.

What Lives Above SiteKit

Downstream applications own:

Record synchronization.
Data reconciliation.
Expense approval policy.
Analytics pipelines.
Notifications and human approval workflows.
Domain-specific canonical models.

For example, SiteKit can expose:

const sourceRecords = await source_portal.records.list({ workspaceId });
const destinationRecords = await destination_portal.records.list({ workspaceId });

A separate app decides which source wins a conflict, which destination records should be edited, and whether notifications should be suppressed.

Layering Boundary

SiteKit should keep three layers distinct:

Layer	Owns	Rule
Adapter	Faithful site interface	Names fields, operations, and auth requirements the way the site exposes them.
Mapping	Optional projection into a shared shape	Separately versioned, pure projection over adapter data. No network calls and no business rules.
App	Workflow and domain decisions	Reconciliation, policy, notifications, analytics, and user approvals.

The line between metadata and app logic matters. "This source is authoritative for records in this workspace" is descriptive metadata when it is a reviewed fact about that adapter or connection. "When two systems disagree, edit the destination and notify an owner" is app logic.

If a role is globally true for a site integration, it can live in adapter metadata. If it differs by user, workspace, environment, or team, it belongs in connection or workspace metadata. In either case, SiteKit records the fact; a downstream app decides what to do with it.

Adapter Fidelity First

Adapters should tell the truth about a site. They should not force every website into a universal business schema.

site adapter:
  destination_portal.events.list -> DestinationPortalEvent[]

optional workflow package:
  toOperationalEvent.fromDestinationPortal(...)
  toOperationalEvent.fromSourcePortal(...)

Canonical domain packages may become useful ecosystem packages later. They are not part of the core adapter contract.

Mappings can become their own registry artifacts later:

destination_portal.events.list -> OperationalEvent[]
source_portal.records.list -> OperationalRecord[]

Those mappings should stay pure and testable. They translate shape; they do not sync systems, pick winners, or perform writes.

Product Test

A feature belongs in SiteKit core if it helps create, run, verify, repair, or reuse website adapters.

A feature belongs above SiteKit if it decides what those adapters mean in a specific business domain.