# vhyza/language_detection architecture

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

- Interactive diagram: https://gitdiagram.com/vhyza/language_detection
- Repository: https://github.com/vhyza/language_detection

## Overview

##### Main Components
- Ruby Wrapper/Interface: Under the “lib” directory you have Ruby classes and helper modules (e.g., language.rb, string.rb, version.rb) which expose the API to the end user. This is the user-facing part that applications integrate.
- Native Extension: In the “ext/cld” directory, you see the complete C/C++ sources, including Makefiles and build scripts. This code builds the native extension that provides compact language detection functionality. It’s a direct port or binding of the Chromium Compact Language Detector.
- Test Suite: There’s a “test” directory (with files like language_detection_test.rb and test helpers) to verify the integrated behavior of both Ruby wrappers and underlying native code.
- Build & Configuration: Files like Gemfile, Rakefile, and .gitignore indicate how the project is built and distributed as a Ruby gem, including the native extension build process.

##### Relationships and Interactions
- The Ruby Wrapper (lib/) calls into the native extension compiled from the C/C++ sources (ext/cld). The extension is loaded into the Ruby runtime to expose methods such as “LanguageDetection.perform” or via mixed-in functionality (e.g., adding a “language” instance method).
- When a Ruby application invokes language detection (either by a direct call or via a String extension), it delegates work to the compiled native extension. This two-tier layer ensures that the detection algorithm (written in C/C++) operates behind a Ruby-friendly API.
- The test suite validates both the Ruby layer and the integration with the native code, ensuring that any changes in the native binding properly reflect in the API behavior.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The architecture clearly distinguishes between the high-level Ruby API and the low-level native implementation. This separation ensures that changes in one layer (e.g., optimization in C++ for detection) do not impact the Ruby interface.
- Language Binding Pattern: The design leverages the common pattern of wrapping a native library (Chromium CLD) with language-specific bindings to make it accessible to Ruby developers.
- Modular and Extensible Structure: With modular directories (ext/, lib/, test/), the design allows isolated development, testing, and easy integration of future features.

##### Technologies, Frameworks, and Libraries Involved
- Ruby: The primary language for the public API and gem packaging.
- C/C++: Provides the language detection functionality. Notice the use of Makefiles and configuration headers in the “ext/cld” directory.
- Build Tools: Rake for Ruby gem tasks and Make (via Makefile) for building the native extension.
- Chromium Compact Language Detector: The original source code which serves as the foundation of the language detection algorithm.

##### Instructing the Principal Software Engineer
- Use clear labels for each component. For example:
- “Ruby API Layer (lib/)”
- “Native Extension (ext/cld/)”
- “Test Suite (test/)”
- “Build Configurations (Gemfile, Rakefile, Makefile)”
- Build process and how configuration files orchestrate the compilation of the native extension.
- That the integration point (where Ruby loads the native extension) is clearly marked, as it’s a key part of the architecture.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Build & Configuration
    subgraph "Build & Configuration"
        B1["Gemfile"]:::build
        B2["Rakefile"]:::build
        B3["language_detection.gemspec"]:::build
        B4[".gitignore"]:::build
    end

    %% Ruby API Layer
    subgraph "Ruby API Layer (lib/)"
        R1["Ruby Wrapper: language_detection.rb"]:::ruby
        R2["Module: language.rb"]:::ruby
        R3["Module: string.rb"]:::ruby
        R4["Module: version.rb"]:::ruby
    end

    %% Native Extension
    subgraph "Native Extension (ext/cld/)"
        N1["C/C++ CLD Sources"]:::native
        N2["Build Scripts: Makefile & Build Files"]:::native
    end

    %% Test Suite
    subgraph "Test Suite (test/)"
        T1["Test: language_detection_test.rb"]:::test
        T2["Test Helper: _helper.rb"]:::test
        T3["Test Fixtures: fixtures/"]:::test
    end

    %% Connections between Build & Configuration and other layers
    B2 -->|"builds"| N2
    B3 -->|"packages"| R1

    %% Ruby API interacts with Native Extension
    R1 -->|"calls"| N1

    %% Test Suite validates both layers
    T1 -->|"tests"| R1
    T1 -->|"tests"| N1

    %% Styles
    classDef ruby fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef native fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef test fill:#F7DC6F,stroke:#7D6608,stroke-width:2px;
    classDef build fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;

    %% Click Events for Ruby API Layer
    click R1 "https://github.com/vhyza/language_detection/blob/master/lib/language_detection.rb"
    click R2 "https://github.com/vhyza/language_detection/blob/master/lib/language_detection/language.rb"
    click R3 "https://github.com/vhyza/language_detection/blob/master/lib/language_detection/string.rb"
    click R4 "https://github.com/vhyza/language_detection/blob/master/lib/language_detection/version.rb"

    %% Click Events for Native Extension
    click N1 "https://github.com/vhyza/language_detection/tree/master/ext/cld/"
    click N2 "https://github.com/vhyza/language_detection/tree/master/ext/cld/"

    %% Click Events for Test Suite
    click T1 "https://github.com/vhyza/language_detection/blob/master/test/language_detection_test.rb"
    click T2 "https://github.com/vhyza/language_detection/blob/master/test/_helper.rb"
    click T3 "https://github.com/vhyza/language_detection/tree/master/test/fixtures/"

    %% Click Events for Build & Configuration
    click B1 "https://github.com/vhyza/language_detection/tree/master/Gemfile"
    click B2 "https://github.com/vhyza/language_detection/tree/master/Rakefile"
    click B3 "https://github.com/vhyza/language_detection/blob/master/language_detection.gemspec"
    click B4 "https://github.com/vhyza/language_detection/blob/master/.gitignore"
```
