# lclc-data-team/neon_queries architecture

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

- Interactive diagram: https://gitdiagram.com/lclc-data-team/neon_queries
- Repository: https://github.com/lclc-data-team/neon_queries

## Overview

##### Project Type and Purpose
- This is an open-source Python library (package name: `suave_sql`, project documented as “neon_queries”).
- It provides two main modules:
- `sql_funcs.py` – utilities to construct or run SQL queries
- `reporting_funcs.py` – higher-level reporting workflows (e.g., build tables, run examples)
- It includes Sphinx‐based documentation, unit tests, and a CI workflow to build and publish docs.

##### Key Components and Directory Structure
- Code Package (`suave_sql/`)
- `__init__.py`
- `sql_funcs.py`
- `reporting_funcs.py`
- Tests (`tests/`)
- Python tests and Jupyter notebooks (`report_examples.ipynb`)
- Documentation (`docs/`)
- `docs/source/` – Sphinx source: `.rst`, `conf.py`, helper scripts (`generate_table.py`)
- `docs/build/` – built HTML site (to be published)
- Configuration & Tooling
- `pyproject.toml` & `requirements.txt` – define dependencies and build metadata
- `.github/workflows/SphinxBuild.yml` – CI pipeline to build docs on push
- README (`README.md`) points to the project’s published docs site

##### Relationships and Data Flows
- Developer commits → GitHub repo → GitHub Actions triggers →
- Runs Sphinx build → outputs static HTML → published to GitHub Pages
- (Optionally) Runs tests against `suave_sql` code
- `pyproject.toml` + source files → packaging tool (e.g., `poetry` or `pip`) → releases on PyPI
- End user installs package via `pip` → imports `suave_sql` → uses `sql_funcs` & `reporting_funcs` → (internally) connects to external database services

##### Architectural Patterns & Design Principles
- Modular design: clear separation of core SQL utilities vs. reporting logic
- Documentation-as-code: Sphinx sources alongside code, with CI publishing
- Test-driven components: unit tests and example notebooks
- Standard Python packaging (PEP 517/518)

##### Step-by-Step Composition
b. From it, branch to two CI nodes: “Docs Build” and “Test Suite.”
c. “Docs Build” → output to “GitHub Pages.”
d. “Package Build” (from repo) → “PyPI Registry” → “End User Environment.”
- `suave_sql.sql_funcs`
- `suave_sql.reporting_funcs`
g. A side area for “docs/source” feeding into Sphinx → “docs/build/html.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["GitHub Repository"]:::external

    subgraph "CI/CD Pipeline"
        direction TB
        CI_Docs(["Docs Build"]):::ci
        CI_Tests(["Test Suite"]):::ci
        Package(["Package Build"]):::ci
    end

    A -->|"push"| CI_Docs
    A -->|"push"| CI_Tests
    A -->|"push"| Package

    CI_Docs -->|"build docs"| Sphinx["Sphinx"]:::docs
    CI_Tests -->|"run tests"| Tests["tests/"]:::tests

    Sphinx -->|"output HTML"| HTML["docs/build/html/"]:::docs
    HTML -->|"publish"| Pages["GitHub Pages"]:::external

    subgraph "Documentation Source"
        direction TB
        DS_Dir["docs/source/"]:::docs
        Conf["conf.py"]:::docs
        Gen["generate_table.py"]:::docs
        Index["index.rst"]:::docs
        RepDoc["reporting_funcs.rst"]:::docs
        LibDoc["suave_sql.rst"]:::docs
        ExTable["examples_table.rst"]:::docs
        NB_Docs["report_examples.ipynb"]:::docs
    end

    DS_Dir --> Conf
    DS_Dir --> Gen
    DS_Dir --> Index
    DS_Dir --> RepDoc
    DS_Dir --> LibDoc
    DS_Dir --> ExTable
    DS_Dir --> NB_Docs
    DS_Dir --> Sphinx

    A -->|"metadata & deps"| Meta["pyproject.toml\nrequirements.txt"]:::external
    A -->|"CI workflow"| CFG[".github/workflows/SphinxBuild.yml"]:::ci
    A -->|"readme"| Readme["README.md"]:::external

    A -->|"tests folder"| Tests

    A -->|"code package"| LibPackage["suave_sql/"]:::library

    subgraph "End User Environment"
        direction TB
        UUser["User Code"]:::external
        U_SQL["suave_sql.sql_funcs"]:::library
        U_REP["suave_sql.reporting_funcs"]:::library
        U_SQL -->|"SQL execution"| DB["Database Service"]:::external
        UUser -->|"import"| U_SQL
        UUser -->|"import"| U_REP
    end

    Package -->|"publish"| PyPI["PyPI Registry"]:::external
    PyPI -->|"install via pip"| UUser

    %% Click Events
    click LibPackage "https://github.com/lclc-data-team/neon_queries/tree/main/suave_sql/"
    click U_SQL "https://github.com/lclc-data-team/neon_queries/blob/main/suave_sql/sql_funcs.py"
    click U_REP "https://github.com/lclc-data-team/neon_queries/blob/main/suave_sql/reporting_funcs.py"
    click LibPackage "https://github.com/lclc-data-team/neon_queries/blob/main/suave_sql/__init__.py"
    click Tests "https://github.com/lclc-data-team/neon_queries/tree/main/tests/"
    click NB_Docs "https://github.com/lclc-data-team/neon_queries/blob/main/tests/report_examples.ipynb"
    click DS_Dir "https://github.com/lclc-data-team/neon_queries/tree/main/docs/source/"
    click Conf "https://github.com/lclc-data-team/neon_queries/blob/main/docs/source/conf.py"
    click Gen "https://github.com/lclc-data-team/neon_queries/blob/main/docs/source/generate_table.py"
    click Index "https://github.com/lclc-data-team/neon_queries/blob/main/docs/source/index.rst"
    click RepDoc "https://github.com/lclc-data-team/neon_queries/blob/main/docs/source/reporting_funcs.rst"
    click LibDoc "https://github.com/lclc-data-team/neon_queries/blob/main/docs/source/suave_sql.rst"
    click ExTable "https://github.com/lclc-data-team/neon_queries/blob/main/docs/source/examples_table.rst"
    click NB_Docs "https://github.com/lclc-data-team/neon_queries/blob/main/docs/source/report_examples.ipynb"
    click HTML "https://github.com/lclc-data-team/neon_queries/tree/main/docs/build/html/"
    click CFG "https://github.com/lclc-data-team/neon_queries/blob/main/.github/workflows/SphinxBuild.yml"
    click Meta "https://github.com/lclc-data-team/neon_queries/blob/main/pyproject.toml"
    click Meta "https://github.com/lclc-data-team/neon_queries/blob/main/requirements.txt"
    click Readme "https://github.com/lclc-data-team/neon_queries/blob/main/README.md"

    %% Styles
    classDef library fill:#D0E1FF,stroke:#0366d6,color:#0366d6
    classDef ci fill:#e0ffe0,stroke:#28a745,color:#28a745
    classDef docs fill:#fff4e0,stroke:#d89614,color:#d89614
    classDef tests fill:#f3e0ff,stroke:#6f42c1,color:#6f42c1
    classDef external fill:#f0f0f0,stroke:#6c757d,color:#6c757d
```
