# gvlasov/inflectible architecture

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

- Interactive diagram: https://gitdiagram.com/gvlasov/inflectible
- Repository: https://github.com/gvlasov/inflectible

## Overview

##### Project type and purpose
- Inflectible is a Java library (template engine) for building grammatically correct, inflected natural-language strings.
- It uses ANTLR grammars to parse two domain‐specific markup languages—vocabulary markups and template markups—into ASTs and then into internal model objects.

##### High‐level architecture overview
The internal architecture can be thought of as a multi‐stage pipeline with the following logical layers:
a. Markup input (vocabulary definitions & template definitions)
b. ANTLR processing (lexer & parser)
c. Parsed AST model (`org.tendiwa.inflectible.antlr.parsed`)
d. Core model construction (`org.tendiwa.inflectible` core classes like `BasicLexeme`, `BasicTemplate`, `BasicVocabulary`, `NativeSpeaker`)
e. Language‐specific implementations (`org.tendiwa.inflectible.implementations`) & inflection logic (`org.tendiwa.inflectible.inflection`)
f. Application API (user interacts via `NativeSpeaker.fillOut(...)`)

##### Main components
- ANTLR Grammars (src/main/antlr4):
– SharedLexer/SharedParser for shared tokens
– LexemeLexer/LexemeParser for vocabulary markups
– TemplateLexer/TemplateParser for template markups
- Generated Parser Classes (under src/main/java/org/tendiwa/inflectible/antlr)
- Parsed AST classes (package `parsed/`): hold parse‐tree wrappers for lexemes, templates, concepts, placeholders, etc.
- Core Model classes (`org.tendiwa.inflectible`): interfaces (`Vocabulary`, `Template`, `Concept`, `NativeSpeaker`), and basic implementations (`BasicVocabulary`, `BasicTemplate`, `BasicLexeme`, etc.)
- Inflection engine (package `inflection`): algorithms for selecting closest grammatical meaning, suppletive forms, etc.
- Language Implementations (package `implementations`): concrete languages (English, Russian) that supply grammemes, parts of speech, declension rules, built‐in vocabularies.
- User API: `NativeSpeaker` orchestrates parsing, vocabulary loading, template loading, and final text generation.

##### Relationships & data flow
1. User or build‐time plugin provides markup files (vocabulary + template).
2. ANTLR-generated lexer → parser reads markup → produces parse‐tree → mapped into Parsed AST objects.
3. Parsed AST → Core constructors translate AST into domain objects (Lexeme, Template, Vocabulary).
4. Core domain objects + Language implementations + Inflection engine → assembled into a `NativeSpeaker` instance.
5. Application calls `nativeSpeaker.fillOut(templateName, Concept… )` → Core uses vocabulary, grammar rules, inflection logic → produces final string.

##### Architectural patterns & design principles
- Layered pipeline (parsing → AST → model → service)
- Strategy & plugin pattern for languages (implementations can be added)
- Clear separation of concerns: parsing vs. model vs. inflection logic vs. API
- Immutable model objects for thread‐safety

##### Putting it all together
[Markup files] → [ANTLR Grammars & Generated Parsers] → [Parsed AST classes] → [Core Model classes] ↔ [Language implementations & Inflection Engine] → [NativeSpeaker API] → [Final Text].

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Parsing Layer
    subgraph "ANTLR Grammars"
        direction TB
        SL["SharedLexer.g4"]:::parsing
        SP["SharedParser.g4"]:::parsing
        LL["LexemeLexer.g4"]:::parsing
        LP["LexemeParser.g4"]:::parsing
        TL["TemplateLexer.g4"]:::parsing
        TP["TemplateParser.g4"]:::parsing
    end
    click SL "https://github.com/gvlasov/inflectible/blob/master/src/main/antlr4/imports/SharedLexer.g4"
    click SP "https://github.com/gvlasov/inflectible/blob/master/src/main/antlr4/imports/SharedParser.g4"
    click LL "https://github.com/gvlasov/inflectible/blob/master/src/main/antlr4/org/tendiwa/inflectible/antlr/LexemeLexer.g4"
    click LP "https://github.com/gvlasov/inflectible/blob/master/src/main/antlr4/org/tendiwa/inflectible/antlr/LexemeParser.g4"
    click TL "https://github.com/gvlasov/inflectible/blob/master/src/main/antlr4/org/tendiwa/inflectible/antlr/TemplateLexer.g4"
    click TP "https://github.com/gvlasov/inflectible/blob/master/src/main/antlr4/org/tendiwa/inflectible/antlr/TemplateParser.g4"

    GP["Generated Parser Classes"]:::parsing
    click GP "https://github.com/gvlasov/inflectible/tree/master/src/main/java/org/tendiwa/inflectible/antlr"

    %% Model Layer
    PAM["Parsed AST Model"]:::model
    click PAM "https://github.com/gvlasov/inflectible/tree/master/src/main/java/org/tendiwa/inflectible/antlr/parsed"

    CMC["Core Model Classes"]:::model
    click CMC "https://github.com/gvlasov/inflectible/tree/master/src/main/java/org/tendiwa/inflectible"

    %% Logic Layer
    IE["Inflection Engine"]:::logic
    click IE "https://github.com/gvlasov/inflectible/tree/master/src/main/java/org/tendiwa/inflectible/inflection"

    LI["Language Implementations"]:::logic
    click LI "https://github.com/gvlasov/inflectible/tree/master/src/main/java/org/tendiwa/inflectible/implementations"

    %% API Layer
    subgraph "User API"
        direction TB
        NS["NativeSpeaker.java"]:::api
        BNS["BasicNativeSpeaker.java"]:::api
    end
    click NS "https://github.com/gvlasov/inflectible/blob/master/src/main/java/org/tendiwa/inflectible/NativeSpeaker.java"
    click BNS "https://github.com/gvlasov/inflectible/blob/master/src/main/java/org/tendiwa/inflectible/BasicNativeSpeaker.java"

    FT["Final Text"]:::output

    %% Data Flow
    SL --> GP
    SP --> GP
    LL --> GP
    LP --> GP
    TL --> GP
    TP --> GP
    GP --> PAM
    PAM --> CMC
    CMC --> NS
    IE --> NS
    LI --> NS
    NS --> FT

    %% Styles
    classDef parsing fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef model fill:#E6F4EA,stroke:#22863A,color:#22863A;
    classDef logic fill:#FFEECF,stroke:#D73A49,color:#D73A49;
    classDef api fill:#F5F0FF,stroke:#6F42C1,color:#6F42C1;
    classDef output fill:#FFF5B1,stroke:#DBAB09,color:#DBAB09;
```
