architecture overview

Architecture

The Convert Fullstack SDK is built as a set of specialized modules (called "Managers") coordinated by a central Core. Each manager handles one concern — bucketing, rules, data, API communication, etc. — and they collaborate to deliver the full experimentation workflow.

Module Dependency Map

flowchart TD
    A0["ConvertSDK / Core"]
    A1["Context"]
    A2["DataManager"]
    A3["RuleManager"]
    A4["BucketingManager"]
    A5["ApiManager"]
    A6["ExperienceManager"]
    A7["FeatureManager"]
    A8["EventManager"]
    A9["SegmentsManager"]
    A10["Config / Types"]
    A0 -- "Creates" --> A1
    A0 -- "Fetches config via" --> A5
    A0 -- "Fires events via" --> A8
    A1 -- "Runs experiments via" --> A6
    A1 -- "Runs features via" --> A7
    A1 -- "Accesses data via" --> A2
    A1 -- "Evaluates segments via" --> A9
    A1 -- "Releases queues via" --> A5
    A2 -- "Buckets via" --> A4
    A2 -- "Matches rules via" --> A3
    A2 -- "Enqueues tracking via" --> A5
    A2 -- "Fires events via" --> A8
    A2 -- "Uses types from" --> A10
    A6 -- "Gets data/buckets via" --> A2
    A7 -- "Gets data/buckets via" --> A2
    A9 -- "Matches rules via" --> A3
    A9 -- "Stores data via" --> A2
    A0 -- "Uses" --> A2

Loading

The Orchestra Conductor Analogy

Think of the ConvertSDK / Core as the conductor of an orchestra. It's the main starting point you interact with when you first use the SDK.

Just like a conductor:

1. Gets the Music Sheet (Configuration): It takes your initial setup instructions (like your unique project key, called sdkKey) when it starts.
2. Gathers the Musicians (Managers): It creates and organizes all the specialized helper components needed to run experiments.
3. Starts the Performance (Initialization): It fetches the necessary experiment data from Convert servers (if you provided an sdkKey) or uses data you provide directly.
4. Directs the Sections (Provides Context): It allows you to create specific "sessions" for each visitor, ensuring they see the correct variations and their actions are tracked properly. We call these sessions Context objects.

Core Modules

Module	Role	Analogy
ConvertSDK / Core	Entry point. Initializes the SDK, creates managers, fetches config, provides createContext().	Orchestra conductor
Context	Represents a single visitor's session. Runs experiments, features, and tracks conversions for that visitor.	A visitor's personal guide
DataManager	Central data store. Holds project config, coordinates bucketing, caches visitor decisions.	Librarian
ExperienceManager	Retrieves A/B test details and variation assignments for a visitor.	A/B test director
FeatureManager	Resolves feature flag status and variable values for a visitor.	Feature flag controller
BucketingManager	Deterministically assigns visitors to variations using MurmurHash3 hashing.	Sorting Hat
RuleManager	Evaluates targeting rules (audiences) and matching conditions against visitor attributes.	Bouncer
ApiManager	Handles HTTP communication — fetches config from CDN, batches and sends tracking events.	Messenger
EventManager	Internal pub/sub event system for SDK lifecycle events (Ready, Bucketing, Conversion, etc.).	Announcer
SegmentsManager	Evaluates and categorizes visitors into segments for reporting.	Sorting desk
Config / Types	Type definitions, enums, and DTOs used across all modules.	Blueprint

Initialization Flow

When the SDK is initialized, this sequence unfolds:

1. Configuration — The SDK reads the config you provided and sets defaults for unspecified options.
2. Manager Creation — All specialized managers are instantiated and wired together.
3. Data Fetch — If an sdkKey is present, the ApiManager fetches project configuration from Convert's CDN. If a data object is provided directly, it's used immediately (skipping the fetch).
4. Ready State — The EventManager fires the Ready event. The SDK is now ready to create visitor contexts.

sequenceDiagram
    participant UserCode as Your Code
    participant SDK as ConvertSDK
    participant ApiMgr as ApiManager
    participant DataMgr as DataManager
    participant EventMgr as EventManager

    UserCode->>+SDK: Create SDK instance with config
    SDK->>SDK: Create all managers
    SDK->>+ApiMgr: Fetch config from CDN
    ApiMgr-->>-SDK: Return config data
    SDK->>+DataMgr: Store config data
    DataMgr-->>-SDK: Done
    SDK->>+EventMgr: Fire Ready event
    EventMgr-->>-SDK: Done
    SDK-->>-UserCode: SDK is ready

Loading

Platform-Specific Differences

While the architecture is identical across SDKs, there are platform-specific adaptations:

Aspect	JavaScript SDK	PHP SDK	Android SDK	Ruby SDK	iOS SDK	Python SDK
Initialization	new ConvertSDK(config) — async, use onReady() Promise	ConvertSDK::create($config) — synchronous, returns ready instance	ConvertSDK.builder(context)…build() — async, use onReady { } callback	ConvertSdk.create(sdk_key:) — synchronous fetch + install, fires the ready event	ConvertSwiftSDK(configuration:) — async, await sdk.ready() (or a completion-handler overload)	Core(SDKConfig(…)).initialize() — synchronous; direct data is offline, an sdk_key fetches over HTTPS
Config Refresh	setTimeout for periodic background re-fetch	PSR-16 cache TTL handles staleness	dataRefreshInterval timer re-fetches while the app is in the foreground; last-good config cached on disk	Background data_refresh_interval timer (default 300s) re-fetches and fires config.updated; settable to nil (timer off) for Lambda / CLI	dataRefreshIntervalMs timer (default 300s) re-fetches in the background; last-good config cached on disk (Application Support)	Opt-in RefreshConfig background thread (interval_seconds, default 300s, with jitter + exponential backoff) fires CONFIG_UPDATED; off entirely when unset (Lambda / CLI)
HTTP Client	Built-in fetch/XMLHttpRequest	PSR-18 HTTP client (auto-discovered)	OkHttp	Standard-library Net::HTTP (zero runtime deps)	URLSession (system framework, no third-party deps)	httpx (the only runtime dependency); pluggable via the Transport Protocol
Event Queue Flush	Timer-based batching	register_shutdown_function (auto-flush on script end)	Timer-based batching in the foreground; flush on app background, WorkManager retry for offline events	Timer-based batching (flush_interval, default 1s) plus a PID-guarded at_exit auto-flush	Timer-based batching (eventsReleaseIntervalMs, default 1s); on background the queue flushes and survivors persist to a coordinated on-disk file for a background URLSession to deliver	In-process batch queue (batch_size auto-release + opt-in auto_flush_interval_ms daemon timer) plus a best-effort atexit final flush
Data Persistence	Optional custom DataStore interface	PSR-16 cache (dual-purpose: config + visitor data)	Built-in: SharedPreferences (visitor + sticky state) and app-private files (config cache, offline event queue)	In-memory by default; optional pluggable store: (duck-typed get/set), with a built-in RedisStore	Keychain (visitor id, system of record) + app-private coordinated files (config cache + durable offline event queue)	InMemoryDataStore by default; pluggable via the DataStore Protocol (data_store option)
Logging	Built-in LogManager	PSR-3 logger integration	Built-in logger with logLevel(LogLevel) builder option	Built-in LogManager with the log_level option and an optional sink	Built-in logger with the logLevel option (LogLevel, default .warn)	Standard-library logging via the convert_sdk logger namespace

Next Steps

• Data Model Reference — Entity relationships and field definitions
• Experiences & Variations — How A/B tests work
• Bucketing Algorithm — How visitors are assigned to variations