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["ConvertSwiftSDK / 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 ConvertSwiftSDK / 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
ConvertSwiftSDK / 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 ConvertSwiftSDK
    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	iOS SDK
Initialization	new ConvertSwiftSDK(config) — async, use onReady() Promise	ConvertSwiftSDK::create($config) — synchronous, returns ready instance	ConvertSwiftSDK(configuration:) — non-blocking init; await sdk.ready() suspends until config loads
Config Refresh	setTimeout for periodic background re-fetch	PSR-16 cache TTL handles staleness	ConfigRefreshScheduler driven by Task.sleep interval; background URLSession for durable delivery
HTTP Client	Built-in fetch/XMLHttpRequest	PSR-18 HTTP client (auto-discovered)	URLSession (Foundation); background URLSession for out-of-process event upload
Event Queue Flush	Timer-based batching	register_shutdown_function (auto-flush on script end)	Timer-based batching via Task.sleep; persists queue to disk on app background, flushes on foreground
Data Persistence	Optional custom DataStore interface	PSR-16 cache (dual-purpose: config + visitor data)	Keychain (visitor ID) + UserDefaults mirror + coordinated file stores (config cache, event queue)
Logging	Built-in LogManager	PSR-3 logger integration	Logger port (protocol); production default is NoopLogger; injectable for tests
Concurrency	Promises / async-await	Synchronous (PHP request lifecycle)	Swift actors + async/await; all shared mutable state is actor-isolated
Distribution	npm (@convertcom/js-sdk)	Composer (convertcom/convertcom-php-sdk)	Swift Package Manager (ConvertSwiftSDKCore + ConvertSwiftSDK targets) or CocoaPods

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