This page defines how DomiDo talks to external systems. Every provider — Stripe, the OAuth providers, the AI generation providers, the LLM translation provider, media storage, the Docusaurus publication target, email and support, analytics and feature-gate services, and fulfilment partners — is reached through a server-side adapter that enforces explicit timeouts, idempotency, signature verification, retry budgets, safe error mapping, and degrade-first behavior. The frontend never holds provider secrets or calls a provider directly except where the provider explicitly owns a secure hosted flow such as Stripe's card-collection UI. Inbound provider webhooks and callbacks are verified, deduplicated, persisted, and translated into DomiDo domain events before any business state changes. The focus here is the stable integration boundary, not the vendor-specific hosting choices behind it.
Every external provider is reached through a server-owned adapter that enforces timeouts, idempotency, signature verification, retry budgets, and safe error mapping. The universal app talks to the DomiDo API only; it never holds provider secrets or calls a provider directly. Inbound provider webhooks and callbacks are verified, deduplicated, persisted, and translated into DomiDo domain events before any business state changes.
Integrations are isolated behind server-side adapters where secrets, provider-specific payloads, and idempotency handling can be controlled. The frontend interacts with DomiDo APIs rather than provider APIs, with the only exception being a provider's own securely hosted flow — Stripe's card UI is the canonical example. Provider webhooks are signature-verified, idempotent, auditable, and mapped into DomiDo domain events before changing business state, so a redelivery or a malicious replay cannot mutate the platform twice. Provider labels, fees, schedules, and status messages never become hard-coded product truth: they are returned from configuration or read from live provider state, so a Stripe change or a carrier change does not require a frontend release. Provider adapters enforce timeouts, retry budgets, idempotency, safe error mapping, and circuit-breaker or budget-stop behavior before provider failure can exhaust DomiDo workers or spend, so an upstream slowdown becomes a typed degraded response on DomiDo's side rather than runaway cost. Phase A provider resilience is degrade-first: when a provider is slow, unavailable, disabled, or permanently discontinued, DomiDo disables or fails only the affected capability, preserves source and domain state, returns safe retry or unavailable state to the client, and reconciles before changing reservation, committed payment, pre-order, payout, publication, or generated-asset state. Alternate providers are optional before beta and are not assumed by requirements.
| Integration | Phase | Boundary |
|---|---|---|
| Stripe SetupIntent | Phase A.5 | Verifies and saves card references for invited eligible physical-kit pre-orders only. No capture, invoice, shipment, or payout release. |
| Stripe payment capture | Phase B | Captures payment for converted pre-orders or new fulfilment-active orders. |
| Stripe Connect | Phase A.5 / B | Phase A.5 onboarding, KYC, payout settings, and readiness. Phase B payout release only after eligibility. |
| OAuth providers | Phase A | Google, Apple, and Facebook sign-in only. |
| Docusaurus publication | Phase A | Public static help / workshop projection generated from approved content. Runtime comments and support remain DomiDo API data. |
| AI generation providers | Phase A | Projection, model, block-kit, and Promo Studio jobs through async domain jobs. |
| LLM translation provider | Phase A | Server-side async translation of user-generated content into backend-configured languages; no frontend provider calls or secrets. |
| Media storage | Phase A | Private upload / generated / public listing assets through signed references or equivalent safe download / upload actions. |
| Email and support | Phase A | Transactional notices, interest-reservation updates, support conversations, and Phase A.5 / B readiness messages. |
| Analytics and feature-gate service | Phase A | Product analytics and feature-gate evaluation without replacing server-side authorization. |
| Fulfilment and 3PL | Phase B | Order handoff, shipment tracking, returns, replacement workflows. |
Phase A has no Stripe checkout and no card collection for interest reservations — the public interest beta operates entirely outside Stripe's data path. Phase A.5 checkout may create a SetupIntent-backed no-capture pre-order only for invited eligible reservations, and even then it never creates a charge, receipt, invoice, shipment, or payout release. Phase B payment capture uses server-calculated totals and server-owned idempotency; client-supplied prices are ignored. Stripe webhook events are mapped to DomiDo payment-verification, payment-capture, payout-readiness, payout-transfer, dispute, or failure events, and Stripe Connect onboarding and KYC state are displayed through safe requirement labels and readiness states. Raw account, routing, tax, or provider payloads are never exposed to the frontend. All Stripe operations include a safe reconciliation path against Stripe as the source for payment-provider facts; Stripe write operations use stable provider idempotency keys and local trace records so a database retry or a provider retry cannot create duplicate customers, SetupIntents, PaymentIntents, Connect onboarding links, or payout handoffs. For the full implementation of the Phase A.5 SetupIntent flow, webhook handling, Connect onboarding, and reconciliation, see Backend, section 12.
Long-running work uses job resources with a public status, progress, current step, step list, result reference, artifact references, cost and config metadata, retryability, cancellation eligibility, safe error state, timestamps, and polling guidance. The required job classes are projection face generation, user-generated content text translation, model generation and tryout creation, block-kit generation, Promo Studio photo generation, Promo Studio video generation, Docusaurus publication and export, notification dispatch, and Phase B fulfilment sync. The selected queue and worker implementation supports idempotency, lease and heartbeat recovery, retries, cancellation, stale-result protection, dead-letter inspection, and audit correlation. Phase A progress delivery is polling-first through GET /jobs/{jobId}; the app does not depend on server-sent-events or WebSocket progress streaming unless a later requirement adds it.
HTTP handlers never run heavy mesh processing, voxelization, blockification, or external AI provider calls inline — they validate requests, authorize actors, create or reuse idempotent jobs, and return 202. Job creation enforces configured actor and resource concurrency before enqueue, and duplicate idempotent starts reuse the existing job or completed result rather than starting duplicate provider calls or duplicate voxelization. Jobs support poison-job handling, max age and attempt limits, safe manual repair, worker drain and restart recovery, and orphan-artifact cleanup. A failed worker does not publish partial artifacts or overwrite newer source state, so a model job that returns after the user has selected a different tryout is dropped or marked stale rather than clobbering the active selection.
The LLM translation provider is isolated behind a server-side adapter, and the app calls DomiDo APIs only. Translation target languages, provider enablement, fallback order, glossary, and prompt and config version come from backend configuration returned by the translation configuration endpoint, so changing supported languages or tightening the glossary is a configuration change rather than a frontend release. Source mutations persist first and then create async text-translation jobs; provider failure marks translation status as failed or stale and never rolls back the user's source text. Provider requests include only the source field text and minimal field, resource, and audience context needed for translation — payment data, addresses, OAuth identity details, raw provider payloads, and audit actor metadata are never sent to the LLM provider. Translation results are written back to the owning aggregate only when the source checksum still matches the job input; older job results are ignored and audited as stale. Local and automated tests use a deterministic fake translation provider so Web desktop beta testing does not depend on external LLM availability. Translation job creation coalesces by resource, field group, source checksum, target language set, and config version so that repeated saves or retries do not create duplicate provider calls.
Approved help and workshop content is authored and governed in DomiDo admin workflows, and the Docusaurus output is a public projection rather than the source of truth. Runtime comments, likes, reports, support conversations, moderation, and admin actions remain DomiDo API records — the public static output is a build artifact that can be rebuilt at any time from the canonical MongoDB content, but the canonical content is never reconstructed from the static site.
Every integration follows the same family of safe-failure rules. A provider outage produces user-visible retry or degraded state without corrupting domain records. Failed Phase A.5 payment verification keeps checkout recoverable and does not change the source interest reservation except for safe invite or attempt status. Failed reservation-to-pre-order conversion leaves the reservation or pre-order in a conversion-blocked state until resolved. Failed payout readiness blocks release and shows safe remediation labels. Failed generation jobs preserve prior successful draft, scene, and asset state. Failed translation jobs preserve source text, expose source fallback to readers, and support owner and admin retry where the feature surface needs it. Expired worker leases, provider timeouts, cancellation requests, and stale source resources resolve to retryable, cancelled, stale, failed, or dead-lettered job states without publishing partial artifacts or overwriting newer user work. Rate-limit, payload-limit, quota, provider circuit-breaker, and idempotency-conflict failures return typed safe API errors and never mutate domain state or enqueue downstream jobs.
Dependency-specific degradation is defined for MongoDB, object storage, Stripe, OAuth providers, AI and LLM providers, Atlas Search and Vector Search, Docusaurus publication, email and support, analytics, and workers. Each rule defines the user-visible behavior, API status, retry and recovery path, observability signal, and data-safety guard, so an outage in any single integration has a predictable surface for users and a predictable signal for operators. Webhook receivers acknowledge provider events only after signature verification and durable event storage or duplicate recognition; durable-store or enqueue failure returns retryable failure so the provider redelivers. Search and vector outage falls back to configured text search, curated listing cards, or a typed degraded empty state, without ever leaking private drafts, private media, or inactive future-phase resources into the fallback.