OnePlatform — User Stories Friction Point Analysis¶

Date: 2026-06-10 Status: Complete. 108 friction points identified, 22 new ADR decisions required. Method: Three parallel architect agents analyzed three user stories against the 23 approved ADR decisions.

Summary¶

The 23 approved architecture decisions are excellent on security, reliability, and infrastructure. They are thin on user-facing surfaces: the developer experience, the API contracts, the data flow, the app platform, and the plugin system. The architecture designs the engine well but leaves the interfaces to the engine almost entirely unspecified.

Coverage Gaps By Area¶

User Story 1: "I Want to Build an App on the Platform"¶

Personas¶

• Alex — data engineer building a dashboard on ingested data
• Blake — developer building an internal CRUD tool for their team
• Casey — non-expert with a spreadsheet wanting a simple viewer

CRITICAL Friction Points¶

HIGH Friction Points¶

MEDIUM Friction Points¶

User Story 2: "I Want to Build a Plugin to Extend Functionality"¶

Personas¶

• Connector author — adding Shopify data ingestion
• Transformer author — adding custom data masking
• Destination author — adding Snowflake export
• AuthProvider author — adding SAML SSO
• Widget author — adding a custom chart type

CRITICAL Friction Points¶

HIGH Friction Points¶

MEDIUM Friction Points¶

User Story 3: "I Want to Use the API/CLI/SDK"¶

Personas¶

• DevOps engineer — infrastructure-as-code, CI/CD
• Data engineer — trigger pipelines from Airflow
• App developer — external app using OnePlatform data
• Platform admin — manage everything via CLI

CRITICAL Friction Points¶

HIGH Friction Points¶

MEDIUM Friction Points¶

Required New ADR Decisions (Consolidated)¶

The 22 identified gaps consolidate into 13 new architecture decisions (ADR 24–36):

ADR-24: First-Run Experience and Bootstrap¶

• OP_MASTER_KEY generation via init service before other services start
• Bootstrap endpoint POST /api/v1/auth/bootstrap (auto-disables after first use)
• Initial admin + tenant creation flow
• Setup wizard screens and URL
• Docker Compose service startup ordering with health checks

ADR-25: App Platform Design (Hosting, Build, Editor)¶

• App code storage (MinIO/S3-compatible object store, add to Docker Compose)
• Build pipeline (esbuild in Execution Service sandbox for security)
• Build artifact storage and versioning
• App rollback (pointer change to previous version)
• In-browser editor (Monaco Editor, MIT licensed)
• Virtual file system for apps
• Hot-reload preview mechanism
• External IDE support (op app dev local workflow)
• Auto-generated starter app from ontology
• Minimum viable non-expert experience (auto-infer schema, starter app)

ADR-26: App-SDK and BFF Design¶

• Complete API surface of @oneplatform/app-sdk:
• useQuery(entity, options) — typed data access
• useMutation(entity) — write operations
• useSubscription(entity, options) — real-time
• useUser() — current user context
• usePermission(action, resource) — permission check
• useAppStorage(key, default) — per-app/per-user KV
• BFF request flow: browser app → App Service proxy → internal services
• Token handling: httpOnly cookies via App Service BFF
• User identity in app context
• RBAC enforcement at BFF layer

ADR-27: App Access Control and OAuth Client Lifecycle¶

• OAuth client auto-registration on app deploy
• Client ID scheme, redirect URI management
• Token binding to app+user pairs
• Two access modes: Platform-User Only (default) and Public/Guest Access
• Guest role with limited ontology RBAC
• App-level roles separate from platform roles
• Cross-tenant sharing rules

ADR-28: End-to-End Data Flow¶

• Canonical path: Ingestion → raw staging → Ontology mapping → tenant data tables
• Raw data storage (separate from ontology-mapped data)
• Data envelope format (source metadata, ingestion timestamp, record ID)
• Incremental vs full sync (cursor-based with watermark tracking)
• Large dataset handling (batching, backpressure, progress tracking)
• Connector interface specification (methods, configuration schema)
• Auto-inference of ontology from uploaded data / database introspection

ADR-29: API Contract Standard¶

• URL convention: /api/v1/{resource}/{id}
• HTTP method semantics (PATCH for partial, PUT for full replace)
• Request/response envelope: {data: T, meta?: {...}}
• Error format: {error: {code: string, message: string, details?: {}, requestId: string}}
• Pagination: cursor-based {items: T[], nextCursor: string | null, total?: number}
• Filter/sort DSL: ?filter[field]=value&sort=-createdAt&fields=id,name
• Bulk operations: POST /api/v1/{resource}/bulk
• OpenAPI spec at GET /api/v1/openapi.json
• Deprecation/Sunset headers (RFC 8594)
• Health check standard: GET /healthz (liveness), GET /readyz (readiness)

ADR-30: Outbound Event System¶

• Outbound webhook registration CRUD API
• Event catalog (data., pipeline., ingestion., ontology., app., plugin., auth., system.)
• Event schema: {eventId, eventType, tenantId, timestamp, actor, data}
• HMAC-SHA256 signature verification
• Delivery guarantees (at-least-once via BullMQ)
• Retry policy (exponential backoff, max 24h, then dead-letter)
• SSE event replay on reconnection
• Real-time subscription filter syntax
• Connection lifecycle and backpressure

ADR-31: Plugin Interface Specifications¶

• Complete TypeScript interfaces for all 5 plugin types:
• Connector: connect, fetchBatch, subscribeToEvents, disconnect, declareOutputSchema, declareConfigSchema
• Transformer: transform, transformBatch, declareInputSchema, declareOutputSchema
• Destination: write, writeStream, declareAcceptedSchema, declareDeliveryGuarantee
• AuthProvider: validateToken, getAuthorizationUrl, handleCallback, refreshToken, mapClaimsToRoles
• Widget: render, declareDataRequirements, declareSlot (iframe sandbox with postMessage)
• Injected context APIs: CredentialAccessor, FetchProxy, CacheAccessor, PluginLogger, TenantContext, OntologyAccessor
• Plugin error taxonomy: PluginError base + AuthError, RateLimitError, TimeoutError, DataError subtypes
• Complete list of hook stages across all services
• Hook registration API

ADR-32: Plugin Package Format and Distribution¶

• Format: signed tarball (bundle.js + plugin.manifest.json + bundle.js.sha256)
• Manifest schema: name, version, type, entrypoint, configSchema, hooks, requiredExternalUrls, requiredApis, minPlatformVersion, permissions
• Code signing: SHA-256 hash in manifest, optional GPG signing
• Outbound URL allowlist (declared in manifest, admin approves on install)
• Plugin instance model (multiple instances with different configs)
• Per-tenant vs platform-wide configuration
• Plugin registry design (deferred but manifest format compatible)

ADR-33: Plugin Lifecycle and Installation¶

• Installation mechanism: op plugin install accepts local tarball, URL, or registry slug
• Plugin storage after install (Plugin Service database + volume)
• Code distribution: Execution Service fetches from Plugin Service on demand, LRU cache
• Authorization model (platform admin installs, tenant admin configures)
• State machine: draft → installed → enabled → disabled → deprecated → uninstalled
• Graceful disable (in-flight jobs complete, new jobs skip)
• Uninstall requirements (no active jobs, orphaned data prompt)
• Version coexistence (old version held in disabled for 24h rollback window)
• Connector plugin as primary source (separate from hook integration)
• Connector timeout model (configurable per-connector, separate from 30s hook timeout)
• Service RBAC matrix additions: Ingestion→Plugin.listConnectors(), Plugin→Execution.runPlugin()

ADR-34: CLI Design Specification¶

• ~85 commands across 12 groups (auth, profile, user, ontology, data, ingestion, webhook-out, pipeline, exec, app, plugin, logs, config, status, service)
• Credential storage: ~/.config/op/credentials.json, encrypted via system keychain (keytar) with plain-text fallback + warning
• Multi-profile system: ~/.config/op/profiles/
• Environment variable precedence: --flag > OP_* env vars > profile config > defaults
• Output formats: --output json|table|tsv
• Auto-retry on 429 with backoff and progress indicator
• Non-interactive mode flags (--no-input, --yes)
• Tab completion (op completion bash|zsh|fish)
• Standalone binary distribution (GitHub Releases: op-linux-amd64, op-darwin-arm64, etc.)
• Version pinning recommendation for CI

ADR-35: SDK Architecture¶

• OpenAPI code generator: @hey-api/openapi-ts (typed, tree-shakeable)
• Ontology-typed SDK via op sdk generate command (tenant-specific codegen)
• Module format: ESM primary, CJS secondary, dual-package exports
• Browser vs Node detection (auto-select auth strategy)
• Error taxonomy: typed errors with isRetryable, statusCode, code
• Async iterator pagination: sdk.data.list() returns AsyncIterable<Page<T>>
• Auto-retry: configurable RetryPolicy (retry on 429/503, 3 attempts, exponential backoff)
• Real-time subscriptions: sdk.realtime.subscribe(filter, handler) with reconnect/replay

ADR-36: Supporting Infrastructure¶

• API key scoping (data:read, data:write, pipelines:trigger, admin scopes)
• API key rotation workflow with overlap period
• Email delivery: SMTP via OP_SMTP_* env vars, fallback "link-copy" mode
• Predefined role taxonomy (admin, editor, viewer, custom)
• Config export/import specification (YAML, topological sort, conflict resolution modes, dry-run)
• MinIO (MIT, S3-compatible) added to Docker Compose for app builds + file uploads
• CORS policy (OP_ALLOWED_ORIGINS)

Key Recommendations¶

Immediate (before service design begins)¶

1. Write ADR-29 (API Contract Standard) first. Every service implementation bakes in URL conventions, error format, and pagination. Changing later is a platform-wide breaking change.

2. Write ADR-28 (Data Flow) second. This is the #1 value proposition. Without the path from ingestion to queryable data, nothing else matters.

3. Write ADR-31 (Plugin Interfaces) third. The architecture says "built-in features use same interfaces as third-party plugins." Those interfaces must exist before ANY service is implemented.

4. Write ADR-24 (First-Run) early. The bootstrap problem (first user creation, master key generation, startup ordering) must be solved before Docker Compose works.

UX Improvements (beyond fixing gaps)¶

1. Progressive disclosure for ontology editor. Simple mode (table view) + Advanced mode (ER diagram).
2. Instant preview with hot reload. Every save triggers incremental esbuild compile (~100ms).
3. One-command local dev: op app dev --app my-dashboard for external IDE workflow.
4. Guided first-app experience: Sample data → auto-infer schema → generate starter app → deploy in 5 min.
5. Query builder panel in app editor for non-coders.
6. Connection status indicators throughout the platform (data source sync status, pipeline failures, DLQ).
7. Plugin scaffold with sandbox-consistent local dev — if it works locally, it works in production.

Files Reference¶