# xaviermerino/featurematcher architecture

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

- Interactive diagram: https://gitdiagram.com/xaviermerino/featurematcher
- Repository: https://github.com/xaviermerino/featurematcher

## Overview

##### Main Components
- Input Handling: A component that ingests probe and gallery directories (files in .npy format). This input module parses filenames (using regex if provided) to extract subject and label information.
- Core Matching Engine: The processing component (centered on feature_matcher.py) that implements matching logic using Dask for parallel computation. It’s responsible for splitting the workload into chunks (input options are provided for match-chunk-size, label-chunk-size, etc.) and for making the actual comparisons.
- Data Processing & Transformation: Since the tool handles large datasets (using Dask arrays to create numpy arrays from NPZ stacks), use a layer that shows conversion between Dask streams and final in-memory NumPy arrays.
- Output Management: This module generates the score and label outputs. Within the output directory structure, there are subdirectories for authentic and impostor data, containing CSV files and .npy files.
- Docker Runtime Environment: The Dockerfile and attached instructions indicate that the entire tool is containerized, so represent the Docker container as an enclosing boundary that wraps the entire system.
- Optional Test Data Generation: The generate_test_data.py can be depicted as a utility module enabling test and development workflows.

##### Relationships and Interactions
○ From “Input Handler” to “Matching Engine” (which distributes tasks via Dask).
○ From “Matching Engine” to “Output Manager” for saving scores and labels.
- Docker: Enclose these modules in a Docker container that mounts the input directories and output volumes.

##### Architectural Patterns and Technologies
- Command-Line Interface: The project uses a set of argument-based configurations (as detailed in the README) to alter its behavior.
- Containerization: Represent the Docker container as a boundary for deployment with external volume mounts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Container (CLI Tool Environment)"
        direction TB
        dockerEnv["Docker Runtime Environment"]:::container
        fileSystem["File System (Input Directories)"]:::storage
        inputHandler["Input Handling (Probe/Gallery File Reader)"]:::processing
        matchingEngine["Core Matching Engine (Dask Processing and Match Logic)"]:::processing
        dataTransform["Data Transformation (Dask to NumPy Conversion)"]:::processing
        outputManager["Output Management (Score & Label Generation)"]:::storage
        testUtility["Test Data Generation Utility"]:::utility
        
        dockerEnv --> fileSystem
        fileSystem -->|"ingests"| inputHandler
        inputHandler -->|"parses_and_forwards"| matchingEngine
        matchingEngine -->|"processes_tasks"| dataTransform
        dataTransform -->|"transforms_output"| outputManager
        matchingEngine -->|"outputs_scores"| outputManager
    end

    click inputHandler "https://github.com/xaviermerino/featurematcher/blob/main/feature_matcher.py"
    click matchingEngine "https://github.com/xaviermerino/featurematcher/blob/main/feature_matcher.py"
    click dataTransform "https://github.com/xaviermerino/featurematcher/blob/main/feature_matcher.py"
    click outputManager "https://github.com/xaviermerino/featurematcher/blob/main/feature_matcher.py"
    click dockerEnv "https://github.com/xaviermerino/featurematcher/tree/main/Dockerfile"
    click testUtility "https://github.com/xaviermerino/featurematcher/blob/main/generate_test_data.py"

    classDef processing fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef storage fill:#D5E8D4,stroke:#333,stroke-width:2px;
    classDef container fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef utility fill:#FFB6C1,stroke:#333,stroke-width:2px;
```
