# featbit/featbit-dotnet-sdk architecture

> Architecture diagram of the GitHub repository featbit/featbit-dotnet-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/featbit/featbit-dotnet-sdk
- Repository: https://github.com/featbit/featbit-dotnet-sdk

## Overview

##### Main Components
- Application using the SDK: Represent a client application (console app or web API) that instantiates the SDK.
- Core SDK Client (FbClient): This is the heart of the system. It mediates configuration, flag evaluation, event handling, and connectivity.
- Options & Configuration: The components built using FbOptions and FbOptionsBuilder, which configure endpoints (streaming, events), logging, offline mode, etc.
- Bootstrapping Module: Contains providers (like JsonBootstrapProvider and NullBootstrapProvider) used to initialize feature flag data when the client starts, particularly in offline mode.
- Data Synchronizer: Module (e.g., WebSocketDataSynchronizer) that manages the connection to the FeatBit server. This component uses a WebSocket (within the Transport namespace) to listen for push updates for feature flags and segments.
- In-Memory Store: The memory store (DefaultMemoryStore and related store abstractions) where the latest flag data is stored and from where the evaluation layer reads.
- Evaluation Engine: A suite of classes (Evaluator, ConditionMatcher, RuleMatcher, SegmentMatcher, etc.) that process incoming flag evaluation requests by consulting the data in the store.
- Events Pipeline: Consisting of event buffer, event dispatcher, event processor, sender, and serializer. This chain captures evaluation events (or custom events like experiments) and sends them to the FeatBit server.
- Transport Layer: Composed of classes in the Transport namespace (such as FbWebSocket, WebSocketTransport, DuplexPipe, etc.) that encapsulate low-level communication details over WebSocket.
- Retry Mechanism: Modules providing retry policies (IRetryPolicy, DefaultRetryPolicy, BackoffAndJitterRetryPolicy) to handle transient network issues.
- Dependency Injection Support: Provided via the DependencyInjection extensions (such as ServiceCollectionExtensions and FbClientHostedService) that integrate the SDK into ASP.NET Core DI frameworks.
- Logging Integration: The SDK integrates with Microsoft.Extensions.Logging so that events and operations can be logged.

##### Relationship and Interactions
- The client application instantiates the FbClient (configured with FbOptions) and uses it for flag evaluation.
- During initialization, FbClient uses the Bootstrapping module to load an initial snapshot of feature flag data (either from a JSON string in offline mode or via remote retrieval in online mode).
- The Data Synchronizer (using WebSocket Transport) maintains a live connection to the FeatBit server. When changes occur remotely, synchronized updates populate the in-memory store.
- The Evaluation Engine is triggered when the application calls methods such as BoolVariation or BoolVariationDetail. It reads from the in-memory store and applies matching logic (using ConditionMatcher, RuleMatcher, and SegmentMatcher).
- When evaluations or user actions occur, events are generated. These events are captured by the Event Pipeline (event buffer, dispatcher, etc.) and then sent to the specified remote endpoint.
- The Retry and Error-Handling components wrap around the data synchronization and event sending operations to ensure resiliency.
- The Dependency Injection extensions help seamlessly integrate all these components into an ASP.NET Core environment.

##### Key Architectural Patterns and Principles
- Modularization: The SDK breaks down functionality (bootstrapping, synchronization, evaluation, events) into separate namespaces and modules.
- Separation of Concerns: Each module (data synchronization, evaluation, events, transport) is isolated so that changes in one do not affect the others.
- Abstraction and Extensibility: Interfaces like IFbClient, IBootstrapProvider, IDataSynchronizer, etc. allow for custom implementations (e.g., a custom bootstrap provider or an alternative in-memory store).
- Dependency Injection: The use of extension methods to register services via DI fosters easy integration and testing.
- Resilience: Retry policies and fallback components (for offline mode or null implementations) showcase defensive design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application Subgraph
    subgraph "Client Application"
        CA1["Console App"]:::client
        CA2["Web API App"]:::client
    end

    %% Main SDK Core
    FbClient["FbClient (SDK Core)"]:::sdk

    %% Internal Modules around SDK Core
    Options["Options & Configuration"]:::config
    Bootstrapping["Bootstrapping Module"]:::bootstrap
    DataSync["Data Synchronizer"]:::sync
    InMemoryStore["In-Memory Store"]:::store
    EvaluationEngine["Evaluation Engine"]:::evaluation
    EventsPipeline["Events Pipeline"]:::events

    %% Supporting Modules
    Transport["Transport Layer"]:::transport
    Retry["Retry Mechanism"]:::retry
    DI["Dependency Injection Support"]:::dependency
    Logging["Logging Integration"]:::logging

    %% External System
    FeatBitServer["FeatBit Server"]:::external

    %% Connections from Client Application to SDK Core
    CA1 -->|"instantiates"| FbClient
    CA2 -->|"instantiates"| FbClient

    %% SDK Core configuration and initialization
    FbClient -->|"configures"| Options
    FbClient -->|"bootstraps"| Bootstrapping

    %% Data Synchronization and Transport
    FbClient -->|"initiates sync"| DataSync
    DataSync -->|"uses"| Transport
    DataSync -->|"receives" | FeatBitServer
    DataSync -->|"updates"| InMemoryStore

    %% Evaluation Flow
    CA1 -->|"flag evaluation"| EvaluationEngine
    CA2 -->|"flag evaluation"| EvaluationEngine
    EvaluationEngine -->|"reads data"| InMemoryStore

    %% Events Flow
    FbClient -->|"captures events"| EventsPipeline
    EventsPipeline -->|"HTTP event dispatch"| FeatBitServer

    %% Supporting: Retry handles both DataSync and EventsPipeline
    Retry ---|"wraps"| DataSync
    Retry ---|"wraps"| EventsPipeline

    %% Dependency Injection integration with FbClient
    DI ---|"integrates"| FbClient

    %% Logging shared with Transport and EventsPipeline
    Logging ---|"logs"| Transport
    Logging ---|"logs"| EventsPipeline

    %% Click Events for Component Mapping
    click CA1 "https://github.com/featbit/featbit-dotnet-sdk/tree/main/examples/ConsoleApp"
    click CA2 "https://github.com/featbit/featbit-dotnet-sdk/tree/main/examples/WebApiApp"
    click FbClient "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/FbClient.cs"
    click Options "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/Options/FbOptions.cs"
    click Bootstrapping "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/Bootstrapping/JsonBootstrapProvider.cs"
    click DataSync "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/DataSynchronizer/WebSocketDataSynchronizer.cs"
    click InMemoryStore "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/Store/DefaultMemoryStore.cs"
    click EvaluationEngine "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/Evaluation/Evaluator.cs"
    click EventsPipeline "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/Events/DefaultEventBuffer.cs"
    click Transport "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/Transport/FbWebSocket.cs"
    click Retry "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/Retry/IRetryPolicy.cs"
    click DI "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/DependencyInjection/ServiceCollectionExtensions.cs"
    click Logging "https://github.com/featbit/featbit-dotnet-sdk/blob/main/src/FeatBit.ServerSdk/Transport/FbWebSocket.Log.cs"

    %% Class Styles
    classDef client fill:#aee1f9,stroke:#333,stroke-width:2px;
    classDef sdk fill:#cff09e,stroke:#333,stroke-width:2px;
    classDef config fill:#fce38a,stroke:#333,stroke-width:2px;
    classDef bootstrap fill:#ffb4a2,stroke:#333,stroke-width:2px;
    classDef sync fill:#c9cba3,stroke:#333,stroke-width:2px;
    classDef store fill:#bde0fe,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#ffc8dd,stroke:#333,stroke-width:2px;
    classDef events fill:#d0efdf,stroke:#333,stroke-width:2px;
    classDef transport fill:#f9d5e5,stroke:#333,stroke-width:2px;
    classDef retry fill:#e0bbef,stroke:#333,stroke-width:2px;
    classDef dependency fill:#ffdfd3,stroke:#333,stroke-width:2px;
    classDef logging fill:#d3f8e2,stroke:#333,stroke-width:2px;
    classDef external fill:#fddb99,stroke:#333,stroke-width:2px;
```
