# kither12/shezem-rs architecture

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

- Interactive diagram: https://gitdiagram.com/kither12/shezem-rs
- Repository: https://github.com/kither12/shezem-rs

## Overview

##### Project’s Purpose and Overview
- Shezem-rs is designed to index audio files and quickly search for similar audio based on a fingerprinting algorithm inspired by Shazam.
- The tool is a CLI application with two main commands: “index” (to process and save fingerprints) and “search” (to find matches against a saved fingerprint database).

##### Main Components
a. CLI Interface and Command Handling:
- Main module (src/main.rs): Acts as the entry point which parses CLI arguments and routes commands (“index” and “search”).
- Lib module (src/lib.rs): Likely exports the core functionality for reuse in both commands.

b. Audio Processing Pipeline (Indexing):
- Preprocessing: Convert audio from stereo to mono, downsample by filtering frequencies (using IIR low-pass filter), and prepare the audio for further processing.
- Spectrogram Generation (src/spectrogram.rs): Apply the Short-Time Fourier Transform (STFT) with a Hamming window, determine the time-frequency representation, and identify peaks.
- Fingerprinting (src/fingerprint.rs and src/sample.rs): Group significant peaks into fingerprint hashes by using adjacent peak groups (anchor-based addressing using adjacent peaks).

c. Database Management:
- Database module (src/db.rs): Handles creation and storage of the fingerprint index (e.g., writing to a “.db/db.db3” file). This module will be used in both the indexing and searching phases.

d. Utility Functions:
- Utils (src/utils.rs): Contains lower-level utilities that support common tasks across the audio processing pipeline.

##### Relationships and Data Flow
- CLI (src/main.rs) receives commands and directs the flow.
- For “index”:
- Audio Input → Preprocessing → Spectrogram Generation → Fingerprinting → Database Storage (via src/db.rs)
- For “search”:
- Query Audio Input → Same processing pipeline (preprocessing, spectrogram, fingerprint extraction) → Compare with stored fingerprints from the DB → Use temporal coherence and ranking logic to sort and return top matches.

##### Architectural Patterns and Design Principles
- Modular monolithic design: All components are part of a single executable, but the responsibilities are segmented into dedicated modules.
- Separation of concerns: Clearly separate audio signal processing (preprocessing, spectrogram, fingerprinting) from persistence (database handling) and command parsing (CLI).
- Reusability: Core libraries in src/lib.rs integrate shared functionality between commands.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Interface Layer
    CLI["CLI Entry (Command Parsing)"]
    CORE["Core Library Exports"]

    %% Audio Processing Pipeline Subgraph
    subgraph "Audio Processing Pipeline"
        PRE["Preprocessing (Stereo->Mono, Downsample, IIR Filter)"]
        SPEC["Spectrogram Generation (STFT, Hamming window, Peak Detection)"]
        subgraph "Fingerprint Extraction"
            PG["Peak Grouping"]
            HS["Hashing & Sampling"]
        end
    end

    %% Persistence and Search Layer
    DB["Database Storage"]
    SEARCH["Search Process (Fingerprint Comparison & Ranking)"]

    %% Utility Functions (supporting audio processing)
    UTIL["Utility Functions"]

    %% Flow Connections
    CLI -->|"routes to"| CORE
    CORE -->|"initiates"| PRE
    UTIL -->|"supports"| PRE
    PRE -->|"generates"| SPEC
    SPEC -->|"extracts peaks"| PG
    PG -->|"forms fingerprint"| HS
    HS -->|"stores fingerprint"| DB
    HS -->|"initiates search"| SEARCH
    SEARCH -->|"retrieves fingerprints"| DB

    %% Click Events
    click CLI "https://github.com/kither12/shezem-rs/blob/main/src/main.rs"
    click CORE "https://github.com/kither12/shezem-rs/blob/main/src/lib.rs"
    click SPEC "https://github.com/kither12/shezem-rs/blob/main/src/spectrogram.rs"
    click PG "https://github.com/kither12/shezem-rs/blob/main/src/fingerprint.rs"
    click HS "https://github.com/kither12/shezem-rs/blob/main/src/sample.rs"
    click DB "https://github.com/kither12/shezem-rs/blob/main/src/db.rs"
    click UTIL "https://github.com/kither12/shezem-rs/blob/main/src/utils.rs"

    %% Styles
    classDef cli fill:#B4C7E7,stroke:#000,stroke-width:1px;
    classDef core fill:#B4C7E7,stroke:#000,stroke-width:1px;
    classDef audio fill:#FFF2CC,stroke:#000,stroke-width:1px;
    classDef db fill:#C6E0B4,stroke:#000,stroke-width:1px;
    classDef util fill:#F4CCCC,stroke:#000,stroke-width:1px;

    %% Apply styles
    class CLI,CORE cli;
    class PRE,SPEC,PG,HS,SEARCH audio;
    class DB db;
    class UTIL util;
```
