# maafihanene/arabic-stemmers architecture

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

- Interactive diagram: https://gitdiagram.com/maafihanene/arabic-stemmers
- Repository: https://github.com/maafihanene/arabic-stemmers

## Overview

##### Overall Project Purpose and Type
- This is not a full-stack web application but rather a library/tool that serves as a gateway, offering access to a range of stemming engines.
- The README describes each stemmer (Al Khalil, ArabicProcessingCog, Arabic Stemming Toolkit with three algorithms, Assem’s Arabic Light Stemmer, FARASA, lucene-arabic-analyzer, NTLK’s ISRI Stemmer, Qutuf, Shereen Khoja Stemmer, and Tashaphyne), so each one is a component integrated into the proxy.

- Arabic-Stemmers Proxy (Central Controller):
– Acts as the main entry point and orchestration layer.
– Provides a unified API for client code.
- Individual Stemmer Modules:
– Each directory on the file tree (such as alkhalil_morph_sys_stemmer, arabic_processing_cog_stemmer, arabic_stemming_toolkit, etc.) represents a module/component.
– Some modules (e.g., arabic_stemming_toolkit) are further divided into sub-algorithm components (Algo1, Algo2, Algo3).
- Demo and Output Modules:
– Demo scripts (demo.py) in each directory can be represented as sample clients/testing harness and are useful to illustrate integration.
- Dependencies:
– External libraries (requests, beautifulsoup4, nltk, Tashaphyne, etc.)
– Java Runtime Environment (JRE) is required for stemmers that use .jar files such as FARASA, some Arabic Stemming Toolkit algorithms, and Shereen Khoja Stemmer.
- Resources and Configuration:
– Notice the configuration and resource files (for instance, the "config.py" in ArabicProcessingCog and the resources directories in Arabic Stemming Toolkit) that provide necessary data (stop words lists, diacritics, prefixes, etc.).

##### Relationships and Interactions
- The Central Proxy component routes the input (Arabic text) into the corresponding stemming modules based on selection or configuration.
- Each module can be thought of as an independent “service” (even though they all run in the same project) that returns an array of stems.
- Dependencies between components such as connecting Python code to Java-based stemmers (via .jar files) indicate interoperability points – you might want to note these with special labels (e.g., “JRE Dependency”).
- Data flow: Client input → Proxy Routing → Individual Stemmer Module → Processing Input + External Resources → Returning Results back via the unified API.

##### Architectural Patterns and Design Principles
- The design is modular – each stemmer is isolated in its own package or directory.
- Emphasis on extensibility: Adding new stemmers should follow the same pattern.

##### Specific Elements
– From an “API Entry Point” or “Client Interface” to the Proxy.
– From the Proxy to each specific stemmer module.
- Grouping modules that have similar requirements (e.g., group all stemmers that require JRE).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("Client/API Entry"):::client
    Proxy("Arabic-Stemmers Proxy"):::proxy

    Client -->|"sends text"| Proxy

    subgraph "Pure Python Stemmers"
        HK("Al Khalil Morpho Sys Stemmer"):::purePython
        APC("ArabicProcessingCog Stemmer"):::purePython
        ACPConfig("ArabicProcessingCog Config"):::config
        AL("Assem’s Arabic Light Stemmer"):::purePython
        NT("NTLK ISRI Stemmer"):::purePython
        QT("Qutuf Stemmer"):::purePython
        TP("Tashaphyne Stemmer"):::purePython
    end

    subgraph "Java Dependent Stemmers"
        AST1("AST Algo1"):::javaDep
        AST2("AST Algo2"):::javaDep
        AST3("AST Algo3"):::javaDep
        FR("FARASA Stemmer"):::javaDep
        LA("Lucene Arabic Analyzer"):::javaDep
        SK("Shereen Khoja Stemmer"):::javaDep
    end

    Proxy -->|"routes"| HK
    Proxy -->|"routes"| APC
    Proxy -->|"routes"| AL
    Proxy -->|"routes"| NT
    Proxy -->|"routes"| QT
    Proxy -->|"routes"| TP
    Proxy -->|"routes (JRE)"| AST1
    Proxy -->|"routes (JRE)"| AST2
    Proxy -->|"routes (JRE)"| AST3
    Proxy -->|"routes (JRE)"| FR
    Proxy -->|"routes (JRE)"| LA
    Proxy -->|"routes (JRE)"| SK

    HK -->|"returns stems"| Proxy
    APC -->|"returns stems"| Proxy
    AL -->|"returns stems"| Proxy
    NT -->|"returns stems"| Proxy
    QT -->|"returns stems"| Proxy
    TP -->|"returns stems"| Proxy
    AST1 -->|"returns stems"| Proxy
    AST2 -->|"returns stems"| Proxy
    AST3 -->|"returns stems"| Proxy
    FR -->|"returns stems"| Proxy
    LA -->|"returns stems"| Proxy
    SK -->|"returns stems"| Proxy

    APC -->|"uses"| ACPConfig

    Proxy -->|"sends response"| Client

    click Proxy "https://github.com/maafihanene/arabic-stemmers/blob/master/README.md"
    click HK "https://github.com/maafihanene/arabic-stemmers/blob/master/alkhalil_morph_sys_stemmer/alkhalilMorphoSysStemmer.py"
    click APC "https://github.com/maafihanene/arabic-stemmers/blob/master/arabic_processing_cog_stemmer/arabicProcessingCogStemmer.py"
    click ACPConfig "https://github.com/maafihanene/arabic-stemmers/blob/master/arabic_processing_cog_stemmer/arabic_processing_cog/config.py"
    click AST1 "https://github.com/maafihanene/arabic-stemmers/blob/master/arabic_stemming_toolkit/ast-algo1/arabicStemmingToolkitAlgo1.py"
    click AST2 "https://github.com/maafihanene/arabic-stemmers/blob/master/arabic_stemming_toolkit/ast-algo2/arabicStemmingToolkitAlgo2.py"
    click AST3 "https://github.com/maafihanene/arabic-stemmers/blob/master/arabic_stemming_toolkit/ast-algo3/arabicStemmingToolkitAlgo3.py"
    click AL "https://github.com/maafihanene/arabic-stemmers/blob/master/assems_arabic_light_stemmer/assemsArabicLightStemmer.py"
    click FR "https://github.com/maafihanene/arabic-stemmers/blob/master/farasa_stemmer/farasaStemmer.py"
    click LA "https://github.com/maafihanene/arabic-stemmers/blob/master/lucene-arabic-analyzer/luceneArabicAnalyzerStemmer.py"
    click NT "https://github.com/maafihanene/arabic-stemmers/blob/master/ntlk_stemmer/ntlkIsriStemmer.py"
    click QT "https://github.com/maafihanene/arabic-stemmers/blob/master/qutuf_stemmer/qutufStemmer.py"
    click SK "https://github.com/maafihanene/arabic-stemmers/blob/master/shereen_khoja_stemmer/shereenKhojaStemmer.py"
    click TP "https://github.com/maafihanene/arabic-stemmers/blob/master/tashaphyne_stemmer/tashaphyneStemmer.py"

    classDef client fill:#CDE7BE,stroke:#333,stroke-width:2px;
    classDef proxy fill:#F7D794,stroke:#333,stroke-width:2px;
    classDef purePython fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef javaDep fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef config fill:#D5F5E3,stroke:#333,stroke-width:2px;
```
