# gen-too/primat architecture

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

- Interactive diagram: https://gitdiagram.com/gen-too/primat
- Repository: https://github.com/gen-too/primat

## Overview

##### Project Type and Purpose
- PRIMAT is an open-source Java toolbox for privacy-preserving record linkage (PPRL).
- It provides two desktop applications (Data Owner and Linkage Unit) built with JavaFX and Maven.
- It implements a PPRL workflow: data preprocessing, Bloom-filter encoding, blocking/filtering, matching/classification, post-processing, and evaluation.

##### File-Structure Analysis
- Top-level directories:
- datasets/ – sample CSV files for testing.
- primat/ – Maven project root.
- Under primat/src/main/java/dbs/pprl/toolbox/:
- data_owner/ – modules for data owners: preprocessing, encoding, blocking setup, GUI (DataOwnerApp).
- lu/ – modules for linkage unit: blocking, similarity, classification, post-processing, evaluation, GUI (LinkageUnitApp).
- utils/ – shared utilities: CSV I/O, component loader, string/bitset helpers.
- Resources:
- src/main/resources/gui/view & style – FXML views and CSS for JavaFX UIs.

##### Key Architectural Patterns
- Modular “toolbox” structure: separate packages for each PPRL stage (preprocessing, encoding, blocking, matching, evaluation).
- Task/Pipeline pattern: tasks implement a common interface, chained via configuration.
- MVC for GUI: FXML view files + controllers under gui/controller.
- Maven as build and dependency manager.

##### Main Components
a. Data Owner Application
- GUI Layer: JavaFX controllers & FXML (DataOwnerApp).
- Preprocessing Module: Task → various Preprocessors.
- Encoding Module: BloomFilterEncoder, FeatureExtractor, EncoderTask.
- Blocking Setup: BlockingTask & BlockingFunction(s) for data owner.
- Input/Output: CSVReader / CSVWriter.
- Configuration Loader: XML/JSON config objects under config/ (BlockingConfig, CSVInputFileConfig, etc.).
b. Linkage Unit Application
- GUI Layer: JavaFX controllers & FXML (LinkageUnitApp).
- Blocking Module: metric-space & LSH blockers.
- Similarity Calculation Module: SimilarityCalculator(s).
- Classification Module: ThresholdClassificator, AdaptiveThresholdClassificator.
- Post-processing Module: Hungarian, StableMarriage, Hybrid postprocessors.
- Evaluation Module: QualityEvaluator, PseudoMeasureEvaluator, MetricCollector.
- Input/Output: CSVToEncodedRecordTransformer.
c. Shared / Common
- Utilities: CSVReader/Writer, StringUtils, BitSetUtils.
- Data Models: EncodedRecord, PreparedRecord, Attribute Definitions.
- Configuration Objects.

##### Relationships & Data Flows
1. CSV Input (datasets) → Data Owner GUI
2. DataOwnerApp Controller invokes PreprocessingTask → cleans data
3. Preprocessed data → EncodingTask → outputs encoded records (Bloom filters)
4. Encoded records → optionally apply DataOwner blocking rules → export to file
5. LinkageUnitApp loads encoded record files → Blocking Module generates candidate pairs
6. Candidate pairs → Similarity Calculation → CandidatePairWithSimilarity
7. Candidate similarities → Classification Module → match/no-match decisions
8. Matches → Post-processing Module → one-to-one refinement
9. Results → Evaluation Module → metrics & visualizations
10. Outputs → GUI tables / CSVWriter

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Owner Application
    subgraph "Data Owner Application"
        DOApp["DataOwnerApp"]:::gui
        DOCtr["DO Controllers"]:::gui
        DOFXML["FXML Views"]:::gui
        PreTask["PreprocessingTask"]:::core
        Preprocessors["Preprocessors"]:::core
        EncodingTask["EncodingTask"]:::core
        BFEncoders["BloomFilterEncoders"]:::core
        FeatureExt["FeatureExtractors"]:::core
        BlockTask["BlockingTask"]:::core
        BlockFuncs["BlockingFunctions"]:::core
        ConfDO["Config Objects"]:::io
        DataModelsDO["Data Models"]:::shared
    end

    %% Linkage Unit Application
    subgraph "Linkage Unit Application"
        LUApp["LinkageUnitApp"]:::gui
        LUCtrl["LU Controller"]:::gui
        CSVTrans["CSVToEncodedRecordTransformer"]:::shared
        LSBlocking["Metric-space Blocking"]:::core
        StdBlocking["Standard & LSH Blocking"]:::core
        SimCalc["Similarity Calculation"]:::core
        ClassMod["Classification Module"]:::core
        MatchComp["Matching Component"]:::core
        PostProc["Post-processing Module"]:::core
        EvalMod["Evaluation Module"]:::core
    end

    %% Data Stores & Config
    subgraph "Data Stores & Config"
        CSVData[("CSV Dataset")]:::io
        EncodedFile[("Encoded Records File")]:::io
    end

    %% Shared Utilities & Models
    subgraph "Shared Utilities & Models"
        CSVIO["CSVReader/CSVWriter"]:::shared
        Utils["StringUtils/BitSetUtils"]:::shared
        CompLoader["Component Loader & Converters"]:::shared
    end

    %% Data Owner Flow
    CSVData -->|"Raw CSV"| DOApp
    DOApp -.->|"invokes"| PreTask
    PreTask -->|"Preprocessed Records"| EncodingTask
    EncodingTask -->|"Encoded Bloom Filters"| EncodedFile
    DOApp --> ConfDO
    DOApp --> DataModelsDO

    %% Linkage Unit Flow
    EncodedFile -->|"File"| LUApp
    LUApp -.->|"loads"| CSVTrans
    CSVTrans -->|"Encoded Records"| LSBlocking
    CSVTrans -->|"Encoded Records"| StdBlocking
    LSBlocking -->|"Candidate Pairs"| SimCalc
    StdBlocking -->|"Candidate Pairs"| SimCalc
    SimCalc -->|"CandidatePairsWithSimilarity"| ClassMod
    ClassMod -->|"Match/No-match"| PostProc
    PostProc -->|"Refined Matches"| EvalMod
    EvalMod -->|"Metrics"| LUApp
    EvalMod -->|"Outputs"| CSVIO

    %% GUI to Controllers and Views
    DOApp --> DOCtr
    DOApp --> DOFXML
    LUApp --> LUCtrl

    %% Shared Utilities Usage
    PreTask --> CSVIO
    EncodingTask --> CSVIO
    CSVTrans --> CSVIO
    ClassMod --> CompLoader
    SimCalc --> Utils

    %% Click Events
    click DOApp "https://github.com/gen-too/primat/blob/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/gui/DataOwnerApp.java"
    click DOCtr "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/gui/controller/"
    click DOFXML "https://github.com/gen-too/primat/tree/master/primat/src/main/resources/gui/view/"
    click PreTask "https://github.com/gen-too/primat/blob/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/preprocessing/PreprocessingTask.java"
    click Preprocessors "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/preprocessing/preprocessors/"
    click EncodingTask "https://github.com/gen-too/primat/blob/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/encoding/EncodingTask.java"
    click BFEncoders "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/encoding/"
    click FeatureExt "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/encoding/extractor/"
    click BlockTask "https://github.com/gen-too/primat/blob/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/blocking/BlockingTask.java"
    click BlockFuncs "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/blocking/functions/"
    click ConfDO "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/common/config/"
    click DataModelsDO "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/data_owner/data/records/"
    click LUApp "https://github.com/gen-too/primat/blob/master/primat/src/main/java/dbs/pprl/toolbox/lu/gui/LinkageUnitApp.java"
    click LUCtrl "https://github.com/gen-too/primat/blob/master/primat/src/main/java/dbs/pprl/toolbox/lu/gui/LUController.java"
    click LSBlocking "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/lu/blocking/metricSpace/"
    click StdBlocking "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/lu/blocking/standard/"
    click SimCalc "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/lu/similarityCalculation/"
    click ClassMod "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/lu/classification/"
    click MatchComp "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/lu/matching/"
    click PostProc "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/lu/postprocessing/"
    click EvalMod "https://github.com/gen-too/primat/tree/master/primat/src/main/java/dbs/pprl/toolbox/lu/evaluation/"
    click CSVTrans "https://github.com/gen-too/primat/blob/master/primat/src/main/java/dbs/pprl/toolbox/utils/CSVToEncodedRecordTransformer.java"
    click CSVIO "https://github.com/gen-too/primat/blob/master/primat/src/main/java/dbs/pprl/toolbox/utils/CSVReader.java"
    click Utils "https://github.com/gen-too/primat/blob/master/primat/src/main/java/dbs/pprl/toolbox/utils/StringUtils.java"
    click CompLoader "https://github.com/gen-too/primat/blob/master/primat/src/main/java/dbs/pprl/toolbox/utils/ClassNameObjectConverter.java"

    %% Styles
    classDef gui fill:#D6EAF8,stroke:#21618C,color:#1B4F72
    classDef core fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef io fill:#FCF3CF,stroke:#B9770E,color:#7E5109
    classDef shared fill:#E5E7E9,stroke:#707B7C,color:#2C3E50
```
