# tpn/perfecthash architecture

> Architecture diagram of the GitHub repository tpn/perfecthash, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tpn/perfecthash
- Repository: https://github.com/tpn/perfecthash

## Overview

##### High-Level Architecture Components

a) Input Processing Layer
- Keys Input Handler (handles .keys files)
- Configuration Manager (handles .conf files)
- Command Line Interface

b) Core Processing Layer
- Graph Generation Engine
- Hash Function Factory
- Table Generation Engine
- CUDA Acceleration Component (optional parallel processing)

c) Output Generation Layer
- Code Generation Engine
- Build System Integration
- Compilation Manager

##### Component Relationships

- Input files → Input Processing Layer
- Input Processing Layer → Core Processing Layer
- Core Processing Layer → Output Generation Layer
- Output Generation Layer → Final Artifacts (DLL/SO, Headers, Test Files)

##### Key Technical Elements

Specialized components:
- Perfect Hash Algorithm Implementation (Chm01, Chm02)
- Hash Function Variants (MultiplyShiftR, etc.)
- CUDA Integration for parallel processing
- Benchmark/Test Framework

##### Implementation Details

a) Hash Table Generation Pipeline:
- Key Loading → Graph Generation → Hash Function Selection → Code Generation

b) Runtime Implementation:
- Index() Function Flow
- Memory Layout (Assigned[] array)
- Lookup/Insert/Delete Operations

##### Cross-Platform Support

Platform-specific components:
- Windows Build Chain (Visual Studio)
- Linux Build Chain (Make/CMake)
- Shared Components

Use these visual elements:
- Rectangles: Major components
- Diamonds: Decision points
- Blue: Core components
- Green: Input/Output
- Yellow: Processing
- Gray: Platform-specific elements

Important Architectural Notes:
1. The system is primarily a code generator that produces optimized perfect hash table implementations
##### Modular design allowing different hash functions and algorithms

- Clear separation between build-time and runtime components
- Optimization pipeline flow
- Cross-platform compatibility layers
- Performance-critical paths

This will provide a comprehensive view of both the generation tooling and the resulting perfect hash table implementation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Input
        KI[Keys Input Handler]
        CM[Configuration Manager]
        CLI[Command Line Interface]
    end

    subgraph Core
        GE[Graph Generation Engine]
        HF[Hash Function Factory]
        TGE[Table Generation Engine]
        CUDA[CUDA Acceleration]
    end

    subgraph Output
        CG[Code Generation Engine]
        BS[Build System Integration]
        CompM[Compilation Manager]
    end

    subgraph Artifacts
        DLL[DLL/SO Libraries]
        HDR[Header Files]
        TEST[Test Files]
    end

    %% Input Flow
    KI --> GE
    CM --> TGE
    CLI --> TGE

    %% Core Processing
    GE --> HF
    HF --> TGE
    TGE --> CUDA
    CUDA --> TGE

    %% Output Generation
    TGE --> CG
    CG --> BS
    BS --> CompM
    CompM --> DLL
    CompM --> HDR
    CompM --> TEST

    %% Styling
    classDef input fill:#90EE90
    classDef core fill:#ADD8E6
    classDef output fill:#FFE4B5
    classDef artifact fill:#D3D3D3

    class KI,CM,CLI input
    class GE,HF,TGE,CUDA core
    class CG,BS,CompM output
    class DLL,HDR,TEST artifact

    %% Click Events
    click KI "https://github.com/tpn/perfecthash/blob/main/src/PerfectHash/PerfectHashKeys.c"
    click CM "https://github.com/tpn/perfecthash/blob/main/python/perfecthash/config.py"
    click CLI "https://github.com/tpn/perfecthash/blob/main/python/perfecthash/cli.py"
    click GE "https://github.com/tpn/perfecthash/blob/main/src/PerfectHash/Graph.c"
    click HF "https://github.com/tpn/perfecthash/blob/main/src/PerfectHash/PerfectHashTableHash.c"
    click CUDA "https://github.com/tpn/perfecthash/tree/main/src/PerfectHashCuda"
    click CG "https://github.com/tpn/perfecthash/blob/main/src/PerfectHash/Chm01FileWork.c"
    click BS "https://github.com/tpn/perfecthash/tree/main/src/cmake"
    click TGE "https://github.com/tpn/perfecthash/blob/main/src/PerfectHash/PerfectHashTable.c"
```
