# sidhant92/bool-parser-java architecture

> Architecture diagram of the GitHub repository sidhant92/bool-parser-java, 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/sidhant92/bool-parser-java
- Repository: https://github.com/sidhant92/bool-parser-java

## Overview

##### Project Type & Purpose
- This is an open-source Java library (bool-parser-java) that provides functionality for parsing, validating, and evaluating boolean expressions.
- Its main use cases include transforming a textual boolean expression into a parsed tree (using ANTLR-generated parsers) and then evaluating it using various data types (String, Integer, Decimal, etc.).

##### File Structure
- Top-Level Directories and Files:
- The project is structured with a clear Maven/Gradle style using src/main/java for source code and src/test for unit tests.
- Build files (build.gradle, settings.gradle, gradlew) indicate it’s a Java library.
- Package Organization:
- com.github.sidhant92.boolparser/application contains the BooleanExpressionEvaluator class which acts as the API for evaluating expressions.
- com.github.sidhant92.boolparser/constant holds enum-like definitions (DataType, OperatorType, NodeType, etc.) that are used throughout.
- com.github.sidhant92.boolparser/datatype provides a DataType hierarchy and factory (factory pattern) for encapsulating the supported data types.
- com.github.sidhant92.boolparser/domain includes AST node classes (e.g. BooleanNode, NumericRangeNode, InNode) used to represent parts of a boolean expression.
- com.github.sidhant92.boolparser/operator implements various operators; note the inclusion of a factory and service to manage operator creation and usage.
- com.github.sidhant92.boolparser/parser (and subfolder antlr) handles the parsing logic using ANTLR. This is the entry point for converting a string into a structured AST.
- com.github.sidhant92.boolparser/util, exception, and the test packages add utility functions, error handling, and test coverage for each component.

##### High-Level Components
a. Input & Parsing:
- Component: BoolParser (in the parser package)
- Sub-component: ANTLR-based Parser (in parser/antlr) that tokenizes and parses the expression using a provided grammar (BooleanExpression.g4).
- Data Flow: Expression string → ANTLR Lexer/Parser → AST Node generation.

b. AST (Abstract Syntax Tree) Builder:
- Component: Domain Nodes (located in com/github/sidhant92/boolparser/domain)
- These nodes represent various expression types:
- NumericNode, NumericRangeNode, BooleanNode, UnaryNode, InNode

c. Data Types & Operators:
- DataType Factory (in the datatype package) produces concrete data type instances (Boolean, Integer, Long, Decimal, String, Version).
- Operator and Operator Factory (in the operator package) encapsulate logic for comparison and boolean operations.

d. Evaluation Engine:
- Component: BooleanExpressionEvaluator within the application package.
- Data Flow: Received AST → Evaluates the expression against an input Map representing data.
- Interaction: Uses services from the datatype and operator layers and handles exceptions (error flow from exception package).

e. Exception Handling:
- Component: Exception classes (e.g., InvalidExpressionException, ExpressionEvaluationException, etc.) provide standardized error reporting.
- Interaction: Exceptions are raised throughout parsing and evaluation; show these pathways with directed error flows.

f. Testing & Benchmarking (Support Infrastructure):
- Not part of the runtime architecture but important for understanding the component reliability:
- Test classes in src/test validate the logic of parsing and evaluation.

##### Relationships and Interactions
- The Input (a Boolean expression string) to the ANTLR Parser.
- ANTLR Parser to the AST Node Builder indicating a transformation from raw tokens to structured nodes.
- AST Nodes to the Evaluation Engine (BooleanExpressionEvaluator), as the AST represents the structure that the evaluator processes.
- Exception flows to be depicted as feedback loops from Parser/Evaluator back to the caller indicating failure modes.

##### Architectural Patterns & Design Principles
- Factory Pattern: Clearly used in DataTypeFactory and OperatorFactory.
- Separation of Concerns: Parsing logic is separated from data type definitions, operator implementations, and AST node definitions.
- Modularity: The project is organized into logical packages that each fulfill a distinct responsibility (parsing, domain modeling, evaluation, error handling).
- Abstraction: The API (BooleanExpressionEvaluator) abstracts the complexity behind parsing and evaluating boolean expressions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input & Parsing Layer"
        A["Boolean Expression Input"]:::input
        B["ANTLR-based Parser"]:::parsing
        A -->|"parse"| B
    end

    subgraph "AST & Evaluation Layer"
        C["AST Builder"]:::ast
        D["BooleanExpressionEvaluator"]:::evaluation
        B -->|"buildAST"| C
        C -->|"sendAST"| D
    end

    subgraph "Evaluation Dependencies"
        E["DataType Factory"]:::factory
        F["Operator Factory"]:::factory
        G["Operator Service"]:::factory
        D -->|"uses"| E
        D -->|"uses"| F
        D -->|"uses"| G
    end

    H["Exception Handler"]:::exception
    B -->|"error"| H
    D -->|"error"| H

    click B "https://github.com/sidhant92/bool-parser-java/blob/master/src/main/java/com/github/sidhant92/boolparser/parser/antlr/BoolParser.java"
    click C "https://github.com/sidhant92/bool-parser-java/tree/master/src/main/java/com/github/sidhant92/boolparser/domain"
    click D "https://github.com/sidhant92/bool-parser-java/blob/master/src/main/java/com/github/sidhant92/boolparser/application/BooleanExpressionEvaluator.java"
    click E "https://github.com/sidhant92/bool-parser-java/blob/master/src/main/java/com/github/sidhant92/boolparser/datatype/DataTypeFactory.java"
    click F "https://github.com/sidhant92/bool-parser-java/blob/master/src/main/java/com/github/sidhant92/boolparser/operator/OperatorFactory.java"
    click G "https://github.com/sidhant92/bool-parser-java/blob/master/src/main/java/com/github/sidhant92/boolparser/operator/OperatorService.java"
    click H "https://github.com/sidhant92/bool-parser-java/tree/master/src/main/java/com/github/sidhant92/boolparser/exception"

    classDef input fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef parsing fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef ast fill:#ffd700,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef factory fill:#e0ffff,stroke:#333,stroke-width:2px;
    classDef exception fill:#ffcccb,stroke:#333,stroke-width:2px;
```
