# bennycheung/pyfiresql architecture

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

- Interactive diagram: https://gitdiagram.com/bennycheung/pyfiresql
- Repository: https://github.com/bennycheung/pyfiresql

## Overview

##### Project Type and Purpose
- PyFireSQL is a Python library that provides a SQL-like interface to query Cloud Firestore. Essentially, the project takes SQL-like DML statements (SELECT, INSERT, UPDATE, DELETE) and converts them into Firestore queries.
- The goal is to abstract Firestore’s NoSQL query model behind a familiar SQL syntax while handling the translation and execution using a Firebase client.

##### Key Components and Their Responsibilities
a. Query Parsing and Grammar Component:
- Located in the firesql/sql/grammar directory (firesql.lark). This file defines the SQL-like grammar.
- The module firesql/sql/sql_transformer.py and other sql_*.py files (e.g., sql_fire_query.py, sql_fire_insert.py, etc.) use this grammar to parse and transform SQL statements into an intermediate representation ready for execution.

b. Firebase Client / Connection Module:
- Found in firesql/firebase/client.py, this component handles the connection and interfacing with Cloud Firestore.
- It provides methods to connect to Firestore given appropriate credentials and to execute queries once translated.

c. Execution Logic and Query Translator:
- Housed in the firesql/sql directory, including modules like fire_sql.py and sql_fire_client.py. This portion translates the parsed SQL commands to corresponding Firebase queries.
- Several specialized modules (sql_fire_delete.py, sql_fire_insert.py, etc.) indicate that each DML operation has its dedicated handling.

d. Output Formatter:
- The DocPrinter (in firesql/sql/doc_printer.py) is responsible for formatting query results, for instance printing CSV or JSON, which is used by both the programmatic interface and the CLI script.

e. CLI / Scripting Interface:
- The “scripts/firesql-query.py” file provides a command-line interface to accept SQL input, process it via the FireSQL interpreter, and output results.
- This script ties together the client connection, SQL parsing, query execution, and result formatting.

f. Supporting Artifacts:
- Tests: The tests directory includes unit and integration tests ensuring the various components work as expected.
- Documentation: The docs folder and README provide detailed usage instructions and technical references, while notebooks showcase example usages and analytics.
- Notebooks and examples provide usage demos and integration ideas for further validation.

##### Relationships and Interactions
- The user (or a calling script) provides a SQL query through either the CLI (firesql-query.py) or via programmatic interface.
- The query is fed into the FireSQL module which, via the grammar (Lark parser), parses and transforms the SQL input.
- The parsed query is then translated by the execution logic into a series of calls to the FirebaseClient, which sends the appropriate query to Cloud Firestore.
- Results returned from Firestore are then formatted by the DocPrinter (either as CSV or JSON) ready for consumption.
- Additional optional steps include loading the results into a Pandas DataFrame for further analysis.

##### Architectural Patterns and Design Principles
- Modular Design: Components (parser, client, translator, formatter) are well separated into modules under the “firesql” package.
- Separation of Concerns: Parsing, Firebase connection, query execution, and results formatting are each handled in distinct modules.
- Extensibility: The presence of separate modules for each DML operation (SELECT, INSERT, UPDATE, DELETE) suggests the design is built for easy extension and maintenance.
- Command-Line and Programmatic Interfaces: The design caters both to script-based usage via CLI and integration in Python applications.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User/Client"]:::inputStyle
    CLIInterface["CLI Interface (firesql-query.py)"]:::inputStyle
    User --> CLIInterface

    subgraph "Query Processor"
        SQLParser["SQL Parser"]:::processor
        subgraph "Parsing Components"
            SQLGrammar["SQL Grammar"]:::processor
            SQLTransformer["SQL Transformer"]:::processor
        end
        SQLParser --> SQLGrammar
        SQLParser --> SQLTransformer

        Translator["Query Translator/Executor"]:::processor
        subgraph "Translation Components"
            QueryExecutor["Query Executor (fire_sql.py)"]:::processor
            SQLClientAdapter["SQL Client Adapter (sql_fire_client.py)"]:::processor
            QueryHandler["Query Handler (sql_fire_query.py)"]:::processor
            InsertHandler["Insert Handler (sql_fire_insert.py)"]:::processor
            UpdateHandler["Update Handler (sql_fire_update.py)"]:::processor
            DeleteHandler["Delete Handler (sql_fire_delete.py)"]:::processor
        end
        Translator --> QueryExecutor
        Translator --> SQLClientAdapter
        Translator --> QueryHandler
        Translator --> InsertHandler
        Translator --> UpdateHandler
        Translator --> DeleteHandler

        SQLParser --> Translator
    end

    CLIInterface --> SQLParser

    FirebaseClient["Firebase Client"]:::processor
    Translator --> FirebaseClient

    CloudFirestore["Cloud Firestore"]:::external
    FirebaseClient --> CloudFirestore

    DocPrinter["DocPrinter (Output Formatter)"]:::processor
    CloudFirestore --> DocPrinter

    DocPrinter --> CLIInterface

    %% Ancillary components
    Tests["Integration/Unit Tests (tests)"]:::support
    Docs["Documentation & Notebooks (docs/README)"]:::support
    CLIInterface --- Tests
    CLIInterface --- Docs

    %% Click Events
    click SQLGrammar "https://github.com/bennycheung/pyfiresql/blob/main/firesql/sql/grammar/firesql.lark"
    click SQLTransformer "https://github.com/bennycheung/pyfiresql/blob/main/firesql/sql/sql_transformer.py"
    click QueryExecutor "https://github.com/bennycheung/pyfiresql/blob/main/firesql/sql/fire_sql.py"
    click SQLClientAdapter "https://github.com/bennycheung/pyfiresql/blob/main/firesql/sql/sql_fire_client.py"
    click QueryHandler "https://github.com/bennycheung/pyfiresql/blob/main/firesql/sql/sql_fire_query.py"
    click InsertHandler "https://github.com/bennycheung/pyfiresql/blob/main/firesql/sql/sql_fire_insert.py"
    click UpdateHandler "https://github.com/bennycheung/pyfiresql/blob/main/firesql/sql/sql_fire_update.py"
    click DeleteHandler "https://github.com/bennycheung/pyfiresql/blob/main/firesql/sql/sql_fire_delete.py"
    click FirebaseClient "https://github.com/bennycheung/pyfiresql/blob/main/firesql/firebase/client.py"
    click DocPrinter "https://github.com/bennycheung/pyfiresql/blob/main/firesql/sql/doc_printer.py"
    click CLIInterface "https://github.com/bennycheung/pyfiresql/blob/main/scripts/firesql-query.py"

    %% Styles
    classDef inputStyle fill:#9fdf9f,stroke:#333,stroke-width:2px;
    classDef processor fill:#9ec2e8,stroke:#333,stroke-width:2px;
    classDef external fill:#f9c74f,stroke:#d00000,stroke-width:2px;
    classDef support fill:#f0a6ca,stroke:#a020f0,stroke-width:2px;
```
