# pathalgebra/algebraparser architecture

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

- Interactive diagram: https://gitdiagram.com/pathalgebra/algebraparser
- Repository: https://github.com/pathalgebra/algebraparser

## Overview

1. The query parser (which leverages ANTLR-generated classes and the custom grammar) to convert a textual query into a parse tree.
2. The transformer that traverses the parse tree to produce a query plan tree, which details the algebraic operations and is then output to the command line.

##### Major Components
- Input/Query Interface: Represented by the command line where a user enters a query following the specified syntax.
- Query Parser Module: This module is built around the ANTLR framework (with grammar defined in AlgebraGrammar.g4) and the generated parser and lexer classes. It is responsible for converting the input query into a parse tree.
- Parse Tree to Query Plan Transformer: This component traverses the generated parse tree (using listener or visitor patterns as implemented in classes like AlgebraListener.java and various implementations under the “impl” package). It extracts algebraic operations and constructs the query plan tree.
- Main Application Launcher: The “Main” class initializes these components and orchestrates the process, from reading user input to displaying the query plan.
- (Optional) Maven Build & Configuration: Although not part of the runtime architecture, including a note about the Maven project setup (pom.xml) can be useful for understanding dependency management.

##### Relationships and Interactions
- That the parse tree produced by the ANTLR Parser is then passed to the “Parse Tree to Query Plan Transformer” module. This module, implemented primarily in the “parser/impl” package (with classes like BinaryRPQExpression, AlternationPathExpression, etc.), systematically converts the parse tree into a structured query plan tree.
- Finally, indicate that the resulting query plan tree is displayed in the command line via the Main application.

##### Architectural Patterns and Design Principles
- The separation of grammar processing (parsing) and tree transformation (conversion to a query plan) is central to the design.
- The use of the listener/visitor pattern (common in ANTLR projects) for tree traversal should be highlighted.
- The system follows a modular design where each responsibility—parsing versus plan transformation—resides in its own component/layer.
- The integration of build automation using Maven (pom.xml) ensures that dependencies such as ANTLR are correctly managed.

##### Additional Elements
- Labels for each component.
- Annotating some components (like the ANTLR generated code) with notes indicating that these are auto-generated based on the grammar.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User Input (CLI)"]:::cli
    B["Main Application (Entry Point)"]:::main
    subgraph "Query Parser Module"
        P1["Grammar Definition"]:::grammar
        P2["ANTLR Listener"]:::antlr
        P3["ANTLR Generated Sources"]:::antlr
    end
    G["Parse Tree"]:::parser
    D["Query Plan Transformer"]:::transformer
    E["Output: Query Plan (CLI)"]:::cli
    F["Maven Build & Configuration"]:::build

    %% Flow Connections
    A --> B
    B --> P1
    B --> P2
    B --> P3
    P1 --> G
    P2 --> G
    P3 --> G
    G --> D
    D --> E

    %% Maven Build dotted connections to indicate dependency management
    F -.-> B
    F -.-> P1
    F -.-> D

    %% Click Events
    click B "https://github.com/pathalgebra/algebraparser/blob/main/src/main/java/com/gdblab/main/Main.java"
    click P1 "https://github.com/pathalgebra/algebraparser/blob/main/src/main/antlr4/com/gdblab/parser/AlgebraGrammar.g4"
    click P2 "https://github.com/pathalgebra/algebraparser/blob/main/src/main/java/com/gdblab/parser/AlgebraListener.java"
    click P3 "https://github.com/pathalgebra/algebraparser/tree/main/target/generated-sources/antlr4/com/gdblab/parser/"
    click D "https://github.com/pathalgebra/algebraparser/tree/main/src/main/java/com/gdblab/parser/impl"
    click F "https://github.com/pathalgebra/algebraparser/blob/main/pom.xml"

    %% Styles
    classDef cli fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef main fill:#C3FDB8,stroke:#000,stroke-width:2px;
    classDef parser fill:#FDE4A3,stroke:#000,stroke-width:2px;
    classDef grammar fill:#F6AAD8,stroke:#000,stroke-width:2px;
    classDef antlr fill:#FFDDCC,stroke:#000,stroke-width:2px;
    classDef transformer fill:#D3B3F9,stroke:#000,stroke-width:2px;
    classDef build fill:#E2E2E2,stroke:#000,stroke-width:2px;
```
