# kurloc/alchemancer architecture

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

- Interactive diagram: https://gitdiagram.com/kurloc/alchemancer
- Repository: https://github.com/kurloc/alchemancer

## Overview

##### Project Type and Purpose
- This project is a Python library (“Alchemancer”) for advanced query generation and AST parsing that supports multiple SQL variants (Postgres, MySQL, SQLite, etc.). It offers a modular, plugin-like system for configuring various aspects such as resolvers, JSON query support, and more.
- The README and file tree show that the project is structured into a core library (in the “alchemancer” directory), along with adapters/extensions tailored for different databases and frameworks (observed via examples, fastapi, and references in the README to Flask, Django, etc.). It also incorporates testing and CI workflows.

##### Project’s File Structure
- Main Directories:
- alchemancer: Contains the core modules – notably the AST handling, query generation, reflection handling, and type-specific implementations. This directory forms the heart of the library.
- examples: Provides usage examples demonstrating various query capabilities, such as basic resolvers, subqueries, and function support.
- fastapi: Contains an example integration with FastAPI, showing how the library can be used within a web application framework.
- tests: Comprises unit and integration tests along with fixtures that simulate models and database configurations.
- Supporting Files:
- .github: Includes CI configuration files (which indicate linting and testing on push) that ensure code quality.
- Configuration files such as pyproject.toml, setup.py, and pre-commit hooks manage the project’s build and development processes.

##### README
- The README outlines key features such as resolver support (including temporary tables vs. literal subqueries), plugin (module) system for extensibility, and a range of supported databases.

a. Main Components:
- Alchemancer Core:
- AST Handler
- Query Generator
- Reflection Handler
- Core Plugin Hooks (for injecting modules and custom behavior)
- Database-Specific Adapter Modules:
- Separate modules within the core which support various databases (Postgres, MySQL, SQLite, MsSql, Oracle).
- Plugin/Module System:
- The mechanism for adding or overriding behavior (e.g., resolvers for JSON query support, rule systems to control field-level access).
- Framework Integrations/Examples:
- Integration examples for FastAPI (and placeholders for Django and Flask).
- Testing Suite:
- Unit tests, integration tests, and example queries ensuring functionality and stability.
- CI/CD and Tooling:
- Linting and testing workflows as defined in the .github/workflows directory.

b. Relationships and Interactions:
- The Core Library (alchemancer) provides the essential functionality. It is extended by database-specific extensions which are clearly delineated as different modules.
- The Plugin System (Core Plugin Hooks) provides configuration slots where user-defined or extended modules (present in user code via examples or frameworks) can be integrated.
- User Applications (shown in FastAPI or other potential integrations) interface directly with the core, submitting queries that pass through the query generator and resolver pipelines.
- Testing and examples simulate real-world usage, ensuring each component integrates with the others.

c. Architectural Patterns and Design Principles:
- Modularity: Emphasize the separation between the core functionality and its extensions.
- Plug-in/Module Pattern: Clearly separate the parts that allow for custom modules, as described in the README’s “Plugin systems” section.
- Layered Architecture: Represent the layered approach where the query generation logic resides in the core, which interacts with database-specific adaptations and then is invoked by user interface layers.

d. Relevant Technologies, Frameworks, and Libraries:
- Python as the underlying language.
- FastAPI (explicitly represented via the fastapi directory), and potential integrations with Django/Flask.
- Testing frameworks (as seen in the tests directory) along with Docker compose for emulating database environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    F("User Application (FastAPI Integration)"):::integration
    F -->|"sendsQuery"| PH("Core Plugin Hooks"):::plugin

    subgraph "Alchemancer Core"
        AST("AST Handler"):::core
        QG("Query Generator"):::core
        RH("Reflection Handler"):::core
    end

    PH -->|"configures"| AST
    PH -->|"configures"| QG
    PH -->|"extends"| RH

    QG -->|"generatesSQL"| DA("Database Adapters (Postgres,MySQL,SQLite,MsSql,Oracle)"):::adapter

    EX("Usage Examples"):::example
    EX -->|"demonstrates"| PH

    TS("Testing Suite"):::testing
    TS -->|"validates"| QG

    CI("CI/CD & Tooling"):::ci
    CI -->|"triggers"| TS

    %% Click events
    click AST "https://github.com/kurloc/alchemancer/blob/main/alchemancer/ast_handler.py"
    click QG "https://github.com/kurloc/alchemancer/blob/main/alchemancer/query_generator.py"
    click RH "https://github.com/kurloc/alchemancer/blob/main/alchemancer/reflection_handler.py"
    click PH "https://github.com/kurloc/alchemancer/tree/main/alchemancer/types/"
    click DA "https://github.com/kurloc/alchemancer/blob/main/alchemancer/types/query.py"
    click F "https://github.com/kurloc/alchemancer/tree/main/fastapi/"
    click EX "https://github.com/kurloc/alchemancer/tree/main/examples/"
    click TS "https://github.com/kurloc/alchemancer/tree/main/tests/"
    click CI "https://github.com/kurloc/alchemancer/tree/main/.github/workflows/"

    %% Styles
    classDef integration fill:#FFA07A,stroke:#FF7F50,stroke-width:2px;
    classDef plugin fill:#DDA0DD,stroke:#DA70D6,stroke-width:2px;
    classDef core fill:#87CEFA,stroke:#1E90FF,stroke-width:2px;
    classDef adapter fill:#98FB98,stroke:#32CD32,stroke-width:2px;
    classDef example fill:#FFD700,stroke:#FFA500,stroke-width:2px;
    classDef testing fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef ci fill:#D3D3D3,stroke:#A9A9A9,stroke-width:2px;
```
