Repository navigation
Description
Revised goal — library and proxy support, not a downloadable generic app
Design decision (2026-11-13): the generic Syncables interface and its UI code are built into Atomic Server, but run inside a sandboxed iframe, reusing the existing plugin-host isolation / bridge. Built-in does not mean top-level DOM access. No provider-specific or generic Syncables JS bundle is installed from this repository per service.
Companion host issue: ontola/atomic-server#2521
Apps discovery and navigation (Joep alignment)
- The existing Apps entry is in Atomic Server's bottom account menu and opens
/app/apps. Do not add a persistent “Apps” row to the drive resource tree; the earlier clickable demo's row was not part of the implemented sidebar. - Per Joep's accepted marketplace plan, the Apps page is secondary. Discovery is designed to surface in context (Cmd+K Apps group, “Open with”, suggestions, assistant discovery), without assuming all those entry points have shipped.
- Installing GitHub creates a normal platform table in the current drive root, so it naturally appears as a resource in the sidebar. This UI navigation is owned by Atomic Server, not the Syncables library or the proxy.
- The browser Syncables code remains built-in and sandboxed inside an iframe. Provider catalog data is not executable plugin code.
Repository responsibilities
- atomic-plugins keeps
syncables/browser, reusable API discovery and mirroring/reconciliation logic, OpenAPI extensions, provider descriptions/overlays, and the integration proxy. - atomic-server bundles the browser runtime as a dependency, serves the built-in iframe document/module, renders the three views, performs Atomic resource provisioning and enforces per-table permissions.
- integration-proxy owns OAuth, provider tokens, catalog, and credentialed API forwarding. No provider credentials are stored in Atomic or given to frames.
Implementation tasks
- Expose an appropriate browser-safe Syncables API for one selected collection instance with path/context parameter bindings. Keep metadata-driven collection definition vs actual enumerable instance distinct.
- Provide generic collection discovery helpers from composed OpenAPI
crudResourcesand parent/child binding metadata. Handle providers with no enumerable top-level collection. - Preserve stable remote identity and typed values; report pagination coverage, read errors, partial/incomplete responses and rate limits. No implicit remote deletions from missing/partial results.
- Keep an injected transport that can be implemented through Atomic Server's scoped iframe proxy bridge. Do not give an iframe raw OAuth credentials.
- Add a backward-compatible structured service-metadata endpoint to integration-proxy for names, descriptions and optional safe icons;
GET /catalogremains the legacy array of platform IDs and/catalog/{platform}.yamlremains the composed OAD. - Test flat Pets and nested GitHub account → organizations/personal owner namespace → repositories → issues discovery and scoped reads, including idempotent reruns and unsupported collection instances.
Target UI hierarchy (implemented by atomic-server)
Drive root (folder; platforms)
GitHub (normal platform table, SyncableAccountsTable)
GitHub account (row/resource; access, not owner)
Organizations (collection-type table, SyncableCollectionTypeTable)
ontola (canonical organization resource)
Repositories (collection-type table, SyncableCollectionTypeTable)
atomic-server (repository owned by ontola)
Issues (mirrored table, SyncableCollection)
personal owner namespace (not necessarily a GitHub Organization)
Repositories (collection-type table)
personal repository
Issues (mirrored table, SyncableCollection)
An OAuth account grants access to organizations; it does not own them. Repositories are associated with canonical provider owners (organizations or personal owner namespaces), even if accessed via different connected accounts.
These are normal Atomic resources; a user can move/link them. A mirror's identity is the proxy/connection/collection-type/instance binding, never its parent path. Discovery at a parent must not automatically mirror every child.
Out of scope
- Shipping a generic
integrations/syncables/app/ui.jsthat users install per platform. - Choosing a fundamental folder-vs-table model.
- Bidirectional remote writes, provider-specific UI, unrestricted polling or server-side background synchronization for the MVP.
References
syncables/src/browser.ts(describePlatform,readPlatform, injectedTransport)integrations/pets/app/{sync,transport}.ts(working browser integration/typing example)integrations/notion/app(reconciliation/status inspiration)integration-proxy/src/catalog.rs(GET /catalogand OAD endpoints)
History: this issue originally proposed a generic iframe drive app. We retain iframe isolation while moving generic UI/module ownership into Atomic Server instead of a pluggable, externally installed app release.
Product navigation note (2026-11-13)
The Atomic Server host owns Apps navigation. Per Joep's accepted ontola/atomic-server/planning/app-marketplace.md, the Apps page is a secondary discovery destination, already accessible through the bottom sidebar account menu; do not add a permanent top-level Apps row to the drive resource tree as part of this integration work. Future contextual discovery (Cmd+K Apps group, Open with, and relevant suggestions) belongs to the host, not to the Syncables library or integration proxy. A GitHub platform table appears in the sidebar solely because it is a normal installed resource beneath the active drive. This does not alter the iframe security model or account → owner namespace → repositories → Issues hierarchy.
Activity
[-]Generic Syncables drive app: mirror selected proxy collection into an Atomic table[/-][+]Syncables browser discovery & proxy metadata for Atomic Server's built-in iframe views[/+]michielbdejong commentedon Nov 13, 2026
Responsibility split and proxy/Syncables contract are documented in draft PR #734. Generic Syncables UI is built into atomic-server yet kept in a null-origin iframe. This repository maintains the browser library, OpenAPI metadata and proxy catalog capabilities; providers remain declarative. GitHub repositories are owned by an organization or personal namespace rather than by the OAuth account. Runtime implementation and new structured catalog metadata remain follow-up work.
michielbdejong commentedon Nov 13, 2026
Implementation progress (draft PR #734): integration-proxy now exposes a versioned read-only /catalog/apps metadata endpoint without changing the legacy /catalog array or composed OAD route; proxy CI passed after a formatting correction. Syncables/browser now accepts collectionNames to restrict requests to explicitly selected collection definitions plus unresolved parent dependencies, so a selected repository's Issues can be read without traversing unrelated API collections. Tests were added; the latest Syncables CI run is still underway. OAuth/browser host wiring and full E2E are still open.
michielbdejong commentedon Nov 16, 2026
The proxy and library changes are in #734. The structured Apps catalog keeps the legacy endpoint, and the Syncables browser reader can bind and read a selected collection. The dated GitHub catalog includes organization membership discovery and repository-ID Issues reads.
The Atomic Server companion, ontola/atomic-server#2522, passed the native browser flow with protocol-checked PKCE and signed reads against a proxy fixture. Provider credentials stay sealed at the proxy. Live verification remains open until a deployment uses a keyed proxy and the new catalog.
Proxy CI, catalog validation, Syncables CI and integration E2E all passed on the PR head.
michielbdejong commentedon Nov 18, 2026
Live verification is recorded in atomic-server#2522.
The michielbdejong account connected through integrations.atomic.place using the dedicated Atomic Place Integrations OAuth client. Public appears alongside the connected account. Its ontola/atomic-server Issues mirror imported 1,217 issues, matching GitHub's total, with open and closed issue spot checks.
The sidebar expands the source hierarchy and omits issue rows and table-view definitions. Public requests use anonymous GitHub reads with validated cursor pagination. Account-scoped reads retain the signed proxy flow.
The final local run passed both native Chromium workflows with no failures, flakes or skips. Data Browser and E2E typechecks, 81 focused tests, and staged workspace lint passed. Full server CI on 5d3cee05a is queued. The PR remains a draft pending its full validation.