# ahmetaa/zemberek-nlp architecture

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

- Interactive diagram: https://gitdiagram.com/ahmetaa/zemberek-nlp
- Repository: https://github.com/ahmetaa/zemberek-nlp

## Overview

Zemberek-NLP is a Turkish NLP library and service suite. A typical analysis workflow accepts text, tokenizes it, and applies morphology to produce analyses; sentence analysis can also disambiguate. Other documented capabilities include normalization, named-entity recognition, classification, language identification, and language modeling. Console applications and a gRPC server expose selected functions. The graph preserves those documented branches; several subsystem internals are represented at their module level because their implementation was not sampled.

Main entry points: [`morphology/src/main/java/zemberek/morphology/TurkishMorphology.java`](https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/TurkishMorphology.java) (Morphology API), [`morphology/src/main/java/zemberek/morphology/analysis/RuleBasedAnalyzer.java`](https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/analysis/RuleBasedAnalyzer.java) (Morphological Analysis), [`morphology/src/main/java/zemberek/morphology/morphotactics/TurkishMorphotactics.java`](https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/morphotactics/TurkishMorphotactics.java) (Turkish Morphotactics), [`tokenization/src/main/java/zemberek/tokenization/TurkishTokenizer.java`](https://github.com/ahmetaa/zemberek-nlp/blob/master/tokenization/src/main/java/zemberek/tokenization/TurkishTokenizer.java) (Tokenization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_console["Console Apps<br/>[ConsoleApp.java]"]
  node_grpc["gRPC Server"]
  node_morphservice["Morphology Service"]
  node_preprocessservice["Preprocessing Service"]
  node_langservice["Language ID Service"]
end

subgraph group_text["Text Processing"]
  node_tokenizer["Tokenization"]
  node_sentences["Sentence Detection"]
  node_normalization["Normalization"]
end

subgraph group_language["Language Analysis"]
  node_morphology["Morphology API"]
  node_morphanalysis["Morphological Analysis"]
  node_morphotactics["Turkish Morphotactics"]
  node_lexicon["Root Lexicon<br/>[RootLexicon.java]"]
  node_wordgen["Word Generation<br/>[WordGenerator.java]"]
end

subgraph group_models["Models"]
  node_ner["Named Entities<br/>[PerceptronNer.java]"]
  node_classification["Text Classification"]
  node_langid["Language Identification"]
  node_lm["Language Modeling"]
  node_embeddings["Word Embeddings<br/>[FastText.java]"]
end

subgraph group_foundation["Core Foundation"]
  node_core["Core Utilities<br/>[Files.java]"]
  node_turkish["Turkish Language Data"]
end

node_user(("Text User"))

node_morphservice -->|"analyzes text"| node_morphology
node_preprocessservice -->|"tokenizes text"| node_tokenizer
node_langservice -->|"identifies language"| node_langid
node_morphology -->|"tokenizes sentences"| node_tokenizer
node_morphology -->|"delegates analysis"| node_morphanalysis
node_morphology -->|"creates generator"| node_wordgen
node_morphotactics -->|"uses lexicon"| node_lexicon
node_user -.->|"runs applications"| node_console
node_user -.->|"accesses services"| node_grpc
node_morphology -.->|"configures analysis"| node_morphotactics
node_user -.->|"normalizes text"| node_normalization
node_user -.->|"extracts entities"| node_ner
node_user -.->|"classifies text"| node_classification
node_user -.->|"uses language models"| node_lm
node_user -.->|"detects sentences"| node_sentences
node_embeddings -.->|"uses utilities"| node_core
node_morphanalysis -.->|"uses language data"| node_turkish

click node_console "https://github.com/ahmetaa/zemberek-nlp/blob/master/apps/src/main/java/zemberek/apps/ConsoleApp.java"
click node_grpc "https://github.com/ahmetaa/zemberek-nlp/blob/master/grpc/src/main/java/zemberek/grpc/server/ZemberekGrpcServer.java"
click node_morphservice "https://github.com/ahmetaa/zemberek-nlp/blob/master/grpc/src/main/java/zemberek/grpc/server/MorphologyServiceImpl.java"
click node_preprocessservice "https://github.com/ahmetaa/zemberek-nlp/blob/master/grpc/src/main/java/zemberek/grpc/server/PreprocessingServiceImpl.java"
click node_langservice "https://github.com/ahmetaa/zemberek-nlp/blob/master/grpc/src/main/java/zemberek/grpc/server/LanguageIdServiceImpl.java"
click node_tokenizer "https://github.com/ahmetaa/zemberek-nlp/blob/master/tokenization/src/main/java/zemberek/tokenization/TurkishTokenizer.java"
click node_sentences "https://github.com/ahmetaa/zemberek-nlp/blob/master/tokenization/src/main/java/zemberek/tokenization/TurkishSentenceExtractor.java"
click node_normalization "https://github.com/ahmetaa/zemberek-nlp/blob/master/normalization/src/main/java/zemberek/normalization/TurkishSentenceNormalizer.java"
click node_morphology "https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/TurkishMorphology.java"
click node_morphanalysis "https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/analysis/RuleBasedAnalyzer.java"
click node_morphotactics "https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/morphotactics/TurkishMorphotactics.java"
click node_lexicon "https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/lexicon/RootLexicon.java"
click node_wordgen "https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/generator/WordGenerator.java"
click node_ner "https://github.com/ahmetaa/zemberek-nlp/blob/master/ner/src/main/java/zemberek/ner/PerceptronNer.java"
click node_classification "https://github.com/ahmetaa/zemberek-nlp/blob/master/classification/src/main/java/zemberek/classification/FastTextClassifier.java"
click node_langid "https://github.com/ahmetaa/zemberek-nlp/blob/master/lang-id/src/main/java/zemberek/langid/LanguageIdentifier.java"
click node_lm "https://github.com/ahmetaa/zemberek-nlp/blob/master/lm/src/main/java/zemberek/lm/NgramLanguageModel.java"
click node_embeddings "https://github.com/ahmetaa/zemberek-nlp/blob/master/core/src/main/java/zemberek/core/embeddings/FastText.java"
click node_core "https://github.com/ahmetaa/zemberek-nlp/blob/master/core/src/main/java/zemberek/core/io/Files.java"
click node_turkish "https://github.com/ahmetaa/zemberek-nlp/blob/master/core/src/main/java/zemberek/core/turkish/TurkishAlphabet.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_console,node_grpc,node_morphservice,node_preprocessservice,node_langservice,node_user toneBlue
class node_tokenizer,node_sentences,node_normalization toneAmber
class node_morphology,node_morphanalysis,node_morphotactics,node_lexicon,node_wordgen toneMint
class node_ner,node_classification,node_langid,node_lm,node_embeddings toneRose
class node_core,node_turkish toneIndigo
```

## Components

### Interfaces

- [Console Apps](https://github.com/ahmetaa/zemberek-nlp/blob/master/apps/src/main/java/zemberek/apps/ConsoleApp.java): `apps/src/main/java/zemberek/apps/ConsoleApp.java`
- [gRPC Server](https://github.com/ahmetaa/zemberek-nlp/blob/master/grpc/src/main/java/zemberek/grpc/server/ZemberekGrpcServer.java): `grpc/src/main/java/zemberek/grpc/server/ZemberekGrpcServer.java`
- [Morphology Service](https://github.com/ahmetaa/zemberek-nlp/blob/master/grpc/src/main/java/zemberek/grpc/server/MorphologyServiceImpl.java): `grpc/src/main/java/zemberek/grpc/server/MorphologyServiceImpl.java`
- [Preprocessing Service](https://github.com/ahmetaa/zemberek-nlp/blob/master/grpc/src/main/java/zemberek/grpc/server/PreprocessingServiceImpl.java): `grpc/src/main/java/zemberek/grpc/server/PreprocessingServiceImpl.java`
- [Language ID Service](https://github.com/ahmetaa/zemberek-nlp/blob/master/grpc/src/main/java/zemberek/grpc/server/LanguageIdServiceImpl.java): `grpc/src/main/java/zemberek/grpc/server/LanguageIdServiceImpl.java`

### Text Processing

- [Tokenization](https://github.com/ahmetaa/zemberek-nlp/blob/master/tokenization/src/main/java/zemberek/tokenization/TurkishTokenizer.java): `tokenization/src/main/java/zemberek/tokenization/TurkishTokenizer.java`
- [Sentence Detection](https://github.com/ahmetaa/zemberek-nlp/blob/master/tokenization/src/main/java/zemberek/tokenization/TurkishSentenceExtractor.java): `tokenization/src/main/java/zemberek/tokenization/TurkishSentenceExtractor.java`
- [Normalization](https://github.com/ahmetaa/zemberek-nlp/blob/master/normalization/src/main/java/zemberek/normalization/TurkishSentenceNormalizer.java): `normalization/src/main/java/zemberek/normalization/TurkishSentenceNormalizer.java`

### Language Analysis

- [Morphology API](https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/TurkishMorphology.java): `morphology/src/main/java/zemberek/morphology/TurkishMorphology.java`
- [Morphological Analysis](https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/analysis/RuleBasedAnalyzer.java): `morphology/src/main/java/zemberek/morphology/analysis/RuleBasedAnalyzer.java`
- [Turkish Morphotactics](https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/morphotactics/TurkishMorphotactics.java): `morphology/src/main/java/zemberek/morphology/morphotactics/TurkishMorphotactics.java`
- [Root Lexicon](https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/lexicon/RootLexicon.java): `morphology/src/main/java/zemberek/morphology/lexicon/RootLexicon.java`
- [Word Generation](https://github.com/ahmetaa/zemberek-nlp/blob/master/morphology/src/main/java/zemberek/morphology/generator/WordGenerator.java): `morphology/src/main/java/zemberek/morphology/generator/WordGenerator.java`

### Models

- [Named Entities](https://github.com/ahmetaa/zemberek-nlp/blob/master/ner/src/main/java/zemberek/ner/PerceptronNer.java): `ner/src/main/java/zemberek/ner/PerceptronNer.java`
- [Text Classification](https://github.com/ahmetaa/zemberek-nlp/blob/master/classification/src/main/java/zemberek/classification/FastTextClassifier.java): `classification/src/main/java/zemberek/classification/FastTextClassifier.java`
- [Language Identification](https://github.com/ahmetaa/zemberek-nlp/blob/master/lang-id/src/main/java/zemberek/langid/LanguageIdentifier.java): `lang-id/src/main/java/zemberek/langid/LanguageIdentifier.java`
- [Language Modeling](https://github.com/ahmetaa/zemberek-nlp/blob/master/lm/src/main/java/zemberek/lm/NgramLanguageModel.java): `lm/src/main/java/zemberek/lm/NgramLanguageModel.java`
- [Word Embeddings](https://github.com/ahmetaa/zemberek-nlp/blob/master/core/src/main/java/zemberek/core/embeddings/FastText.java): `core/src/main/java/zemberek/core/embeddings/FastText.java`

### Core Foundation

- [Core Utilities](https://github.com/ahmetaa/zemberek-nlp/blob/master/core/src/main/java/zemberek/core/io/Files.java): `core/src/main/java/zemberek/core/io/Files.java`
- [Turkish Language Data](https://github.com/ahmetaa/zemberek-nlp/blob/master/core/src/main/java/zemberek/core/turkish/TurkishAlphabet.java): `core/src/main/java/zemberek/core/turkish/TurkishAlphabet.java`

### Other components

- **Text User**

## Connections

- Morphology Service → Morphology API: analyzes text (evidence: `grpc/src/main/java/zemberek/grpc/server/MorphologyServiceImpl.java`)
- Preprocessing Service → Tokenization: tokenizes text (evidence: `grpc/src/main/java/zemberek/grpc/server/PreprocessingServiceImpl.java`)
- Language ID Service → Language Identification: identifies language (evidence: `grpc/src/main/java/zemberek/grpc/server/LanguageIdServiceImpl.java`)
- Morphology API → Tokenization: tokenizes sentences (evidence: `morphology/src/main/java/zemberek/morphology/TurkishMorphology.java`)
- Morphology API → Morphological Analysis: delegates analysis (evidence: `morphology/src/main/java/zemberek/morphology/TurkishMorphology.java`)
- Morphology API → Word Generation: creates generator (evidence: `morphology/src/main/java/zemberek/morphology/TurkishMorphology.java`)
- Turkish Morphotactics → Root Lexicon: uses lexicon (evidence: `morphology/src/main/java/zemberek/morphology/morphotactics/TurkishMorphotactics.java`)
- Text User → Console Apps: runs applications (evidence: `README.md`)
- Text User → gRPC Server: accesses services (evidence: `README.md`)
- Morphology API → Turkish Morphotactics: configures analysis (evidence: `morphology/src/main/java/zemberek/morphology/TurkishMorphology.java`)
- Text User → Normalization: normalizes text (evidence: `README.md`)
- Text User → Named Entities: extracts entities (evidence: `README.md`)
- Text User → Text Classification: classifies text (evidence: `README.md`)
- Text User → Language Modeling: uses language models (evidence: `README.md`)
- Text User → Sentence Detection: detects sentences (evidence: `README.md`)
- Word Embeddings → Core Utilities: uses utilities
- Morphological Analysis → Turkish Language Data: uses language data
