Skip to main content

Providers & Adapters

At the heart of Archibald's architecture is the Provider & Adapter pattern. This pattern acts as a decoupling layer, translating Archibald's generic framework interfaces into specific API and SDK calls for chosen third-party systems (such as Contentful, hybris, etc.).

The Provider & Adapter Pattern​

This architecture splits responsibility between the server-side runtime and client-side browser:

  1. Providers (Server-Side): Fetch data directly from third-party APIs during Server-Side Rendering (SSR).
  2. Adapters (Client-Side): Intercept/delegate client-side operations (like preview updates or async client actions) back to the server or local endpoints.

By maintaining separate provider and adapter abstractions, UI components remain completely agnostic of the underlying CMS or Commerce backend, making migrations or multi-vendor setups straightforward.

Server-Side Providers (CMSProvider)​

A CMSProvider (or generic Provider) is a server-side class that extends @archibald/server's DefaultProvider. Its primary responsibility is to fetch data directly from your service's API during Server-Side Rendering (SSR).

How it Works​

  • Encapsulation: It implements the logic for getPage(), getPreviewContext(), etc., by making HTTP requests to your CMS or backend. It then transforms the raw response using Data Mappers into standard models.
  • SSR Enablement: For SSR to function, the server must fetch all necessary content before sending the final HTML to the browser. The server-side provider makes this possible.
  • Inheritance: The base CMSProvider is an abstract class inheriting from DefaultProvider, meaning you must implement its abstract methods when creating your own.

Client-Side Adapters (CMSAdapter)​

A CMSAdapter (or generic Adapter) is a client-side class that extends @archibald/cms's CMSAdapter. It defines how the client-side application interacts with the third-party system.

How it Works​

  • Delegation: It mirrors the provider's methods (like getPage()), but instead of calling the external API directly, it typically makes requests to your application's own backend proxy (which then securely invokes the CMSProvider).
  • Live Preview & Interactivity: Handles client-specific features such as real-time draft previews, localized storage, and interactive client-side updates.
  • Interface Safety: The base CMSAdapter provides default methods that throw a "Method not implemented" error, ensuring you only need to override the specific methods relevant to your integration.