# hsnkh12/query-language-interpreter architecture

> Architecture diagram of the GitHub repository hsnkh12/query-language-interpreter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hsnkh12/query-language-interpreter
- Repository: https://github.com/hsnkh12/query-language-interpreter

## Overview

##### Project type and purpose
- From the README and file tree, this is a language-processing tool: a custom query-language interpreter written in Go. It is not a full-stack web app but rather a CLI-driven compiler/interpreter pipeline designed to read queries, parse them, type-check them, and execute them via a query manager (presumably against an in-memory or external data store).

##### File structure
- cmd/main.go           → the CLI entry point that reads user input or script files.
- internal/query_parser → implements the lexer (lexer.go), parser (parser.go), and type checkers (type_checkers.go). It produces an AST or intermediate representation.
- internal/query_interpreter → walks the AST, interprets commands, and plumbs through the query manager.
- internal/query_manager     → dispatches parsed, checked queries into actual execution logic (CRUD operations on projects, collections, documents).
- internal/query_interpreter/types.go & parser/types.go → shared AST and semantic data types.
- tests/                → unit tests for parser and interpreter components.
- go.mod                → Go module definition.
- query_language.txt    → spec or examples of the custom language.

##### README for additional insights
- The README defines the DSL commands (“create project …”, “get from … where …”) and indicates that this combines a lexical analyzer, syntax analyzer, type checker, and interpreter.
- There is no built-in database connector in the tree; the “query_manager” likely abstracts document store operations (in memory or via an adapter you may add later).

##### Final advice
- Clearly label interfaces (e.g., QueryManager interface) versus implementations.
- Call out the extension point in QueryManager for plugging real DB backends.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Entry Point
    CLI["CLI / Front Controller\n(cmd/main.go)"]:::frontend
    click CLI "https://github.com/hsnkh12/query-language-interpreter/blob/main/cmd/main.go"

    %% Parsing Stage
    subgraph "Query Parser Module" 
        direction TB
        Lexer["Lexer\n(internal/query_parser/lexer.go)"]:::parsing
        Parser["Parser\n(internal/query_parser/parser.go)"]:::parsing
        TypeChecker["Type Checker\n(internal/query_parser/type_checkers.go)"]:::parsing
        ParserTypes["AST & Semantic Types\n(internal/query_parser/types.go)"]:::parsing
        click Lexer "https://github.com/hsnkh12/query-language-interpreter/blob/main/internal/query_parser/lexer.go"
        click Parser "https://github.com/hsnkh12/query-language-interpreter/blob/main/internal/query_parser/parser.go"
        click TypeChecker "https://github.com/hsnkh12/query-language-interpreter/blob/main/internal/query_parser/type_checkers.go"
        click ParserTypes "https://github.com/hsnkh12/query-language-interpreter/blob/main/internal/query_parser/types.go"
    end

    %% Execution Stage
    subgraph "Execution Stage"
        direction TB
        Interpreter["Query Interpreter\n(internal/query_interpreter/interpreter.go)"]:::execution
        InterpreterTypes["Runtime Types\n(internal/query_interpreter/types.go)"]:::execution
        click Interpreter "https://github.com/hsnkh12/query-language-interpreter/blob/main/internal/query_interpreter/interpreter.go"
        click InterpreterTypes "https://github.com/hsnkh12/query-language-interpreter/blob/main/internal/query_interpreter/types.go"
        QueryManager["Query Manager\n(internal/query_manager/query_manager.go)"]:::execution
        click QueryManager "https://github.com/hsnkh12/query-language-interpreter/blob/main/internal/query_manager/query_manager.go"
    end

    %% Data Store
    DataStore["Data Store\n(In-Memory / Plug-in DB)"]:::datastore

    %% Language Spec & Config
    LangSpec["Language Reference\n(query_language.txt)"]:::docs
    click LangSpec "https://github.com/hsnkh12/query-language-interpreter/blob/main/query_language.txt"
    GoMod["Go Module Definition\n(go.mod)"]:::docs
    click GoMod "https://github.com/hsnkh12/query-language-interpreter/blob/main/go.mod"
    README["Project README\n(README.md)"]:::docs
    click README "https://github.com/hsnkh12/query-language-interpreter/blob/main/README.md"

    %% Tests Coverage
    subgraph "Tests (Coverage)"
        direction TB
        ParserTests["Parser Tests\n(tests/query_parser_test.go)"]:::test
        InterpreterTests["Interpreter Tests\n(tests/query_interpreter_test.go)"]:::test
        click ParserTests "https://github.com/hsnkh12/query-language-interpreter/blob/main/tests/query_parser_test.go"
        click InterpreterTests "https://github.com/hsnkh12/query-language-interpreter/blob/main/tests/query_interpreter_test.go"
    end

    %% Connections
    CLI -->|"user input / script"| Lexer
    Lexer -->|"[]Token"| Parser
    Parser -->|"AST Nodes"| ParserTypes
    ParserTypes --> TypeChecker
    TypeChecker -->|"Typed AST"| Interpreter
    Interpreter --> InterpreterTypes
    Interpreter -->|"Execution Commands"| QueryManager
    QueryManager -->|"CRUD Operations"| DataStore
    DataStore -->|"Results"| CLI

    %% Auxiliary docs connections
    CLI --- README
    QueryManager --- LangSpec
    CLI --- GoMod
    Parser --- ParserTests
    Interpreter --- InterpreterTests

    %% Legend
    subgraph "Legend"
        direction LR
        F["Frontend (CLI)"]:::frontend
        P["Parsing Stage"]:::parsing
        E["Execution Stage"]:::execution
        D["Data Store"]:::datastore
        T["Tests"]:::test
        Doc["Docs / Config"]:::docs
    end

    %% Styles
    classDef frontend fill:#A3BE8C,stroke:#2E3440,color:#2E3440;
    classDef parsing fill:#5E81AC,stroke:#2E3440,color:#ECEFF4;
    classDef execution fill:#A3BE8C,stroke:#2E3440,color:#2E3440;
    classDef datastore fill:#D8DEE9,stroke:#4C566A,color:#2E3440;
    classDef test fill:#EBCB8B,stroke:#2E3440,color:#2E3440;
    classDef docs fill:#88C0D0,stroke:#2E3440,color:#2E3440;
```
