# splatlab/adaptiveqf architecture

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

- Interactive diagram: https://gitdiagram.com/splatlab/adaptiveqf
- Repository: https://github.com/splatlab/adaptiveqf

## Overview

##### Main Components

a. Core AQF Library:
- Main API and implementation. This includes components found in the “include” (headers defining public APIs such as gqf.h, gqf_file.h, etc.) and “src” directories (source files like gqf.c, hash_table.c, partitioned_counter.c, etc.).
- The API functions (qf_malloc, qf_insert_ret, qf_query, qf_remove, qf_adapt, etc.) serve as the entry points to this library.

b. Alternate/ Experimental Filter Implementations:
- These are found under “other_filters” and include variants such as “acf” (Adaptive Cuckoo Filter?), “acfsim”, “cf” (likely Cuckoo Filter variant), “cqf”, and “taf”.
- Each variant typically has its own benchmarks, examples, and sometimes different source implementations. Their subdirectories (src, example, benchmarks) demonstrate both their similarities and differences from the core AQF algorithm.

c. Testing and Benchmarking Components:
- The “test” directory and various “test_*.c” or “test_*.cc” files under “src” and “other_filters” are designed to validate functionality, check performance (e.g., micro, throughput, adversarial cases), and provide integration examples (including the reverse map usage with SplinterDB as shown in the README).

d. External Dependencies and Hardware Considerations:
- The README mentions the dependency on the SSL library (libssl) and the support for different CPU instruction sets (using Haswell instructions or a fallback for older CPUs).

##### Architectural Patterns and Design Principles

- The project is modular: the separation between public header APIs, core implementation (source), and alternative implementations (other_filters) implies a design that favors separation of concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes: Clients, Core, Alternate Variants, Testing & Benchmarking, Hardware & External Dependencies
    Clients["Client Applications/Tests"]:::client
    subgraph "AQF Core"
        API["API Interface (include/*.h)"]:::core
        CoreEngine["Core Filter Engine (src/*.c)"]:::core
    end

    subgraph "Alternate Filter Variants"
        ACF["ACF Variant"]:::variant
        ACFSIM["ACFSIM Variant"]:::variant
        CF["CF Variant"]:::variant
        CQF["CQF Variant"]:::variant
        TAF["TAF Variant"]:::variant
    end

    subgraph "Testing & Benchmarking"
        TestSuite["Test & Benchmark Suite (test/ & src/test_*)"]:::test
    end

    subgraph "Hardware & External Dependencies"
        SSL["libssl"]:::external
        HW["Haswell/Legacy Optimizations"]:::external
    end

    %% Relationships
    Clients -->|"invokes"| API
    API -->|"calls"| CoreEngine
    TestSuite -->|"validates"| API
    CoreEngine -->|"leverages"| HW
    CoreEngine -->|"depends-on"| SSL

    %% Alternate variants integrated via benchmarking tests
    TestSuite -->|"benchmarks"| ACF
    TestSuite -->|"benchmarks"| ACFSIM
    TestSuite -->|"benchmarks"| CF
    TestSuite -->|"benchmarks"| CQF
    TestSuite -->|"benchmarks"| TAF

    %% Styles definitions
    classDef core fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef variant fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef test fill:#abebc6,stroke:#1e8449,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#922b21,stroke-width:2px;
    classDef client fill:#d7bde2,stroke:#6c3483,stroke-width:2px;

    %% Click events as per component mapping
    click API "https://github.com/splatlab/adaptiveqf/tree/main/include/"
    click CoreEngine "https://github.com/splatlab/adaptiveqf/tree/main/src/"
    click ACF "https://github.com/splatlab/adaptiveqf/tree/main/other_filters/acf/"
    click ACFSIM "https://github.com/splatlab/adaptiveqf/tree/main/other_filters/acfsim/"
    click CF "https://github.com/splatlab/adaptiveqf/tree/main/other_filters/cf/"
    click CQF "https://github.com/splatlab/adaptiveqf/tree/main/other_filters/cqf/"
    click TAF "https://github.com/splatlab/adaptiveqf/tree/main/other_filters/taf/"
    click TestSuite "https://github.com/splatlab/adaptiveqf/tree/main/test/"
```
