# jellybrick/requery-ng architecture

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

- Interactive diagram: https://gitdiagram.com/jellybrick/requery-ng
- Repository: https://github.com/jellybrick/requery-ng

## Overview

##### Main Components
- Core Library (requery): This is the main ORM framework that includes the low-level entity mapping, SQL query building, caching, converters, and annotation-based features. It encapsulates key annotations (like @Entity, @Key, @OneToMany) and the entire query DSL.
- Annotation Processor (requery-processor): A dedicated module that parses entity annotations at compile time and generates the necessary entity model and helper classes. It performs validation and code generation so that runtime reflection is not used.
- Platform-Specific Extensions:
– Android Module (requery-android): Provides integration with Android specifics, including SQLite support, content providers, databinding, and even SQLCipher integration.
– Kotlin Module (requery-kotlin): Offers Kotlin-specific language extensions, asynchronous API methods (e.g., using Kotlin coroutines or RxJava), and DSL enhancements.
– Jackson Module (requery-jackson): Integrates with Jackson for JSON serialization/deserialization of entities.
- Test Suites and Examples:
– requery-test (including a Kotlin test sub-module): Contains both unit and integration tests designed to verify the functionality of the core ORM and its extended modules.
– Example projects (such as requery/example-springboot and the Android example under requery-android/example): Demonstrate how the ORM is used within both a Spring Boot environment and an Android application.

##### Relationships and Interactions
- The Core Library provides the fundamental API and abstractions for ORM mapping, query building, transaction management, and caching.
- The Annotation Processor (requery-processor) depends on the core API. It scans annotated code, validates entity definitions, and generates strongly-typed model classes that are then used by the Core Library.
- The platform-specific modules (Android, Kotlin, Jackson) extend or wrap the Core Library interfaces to provide tailored support. For example, the Android module may add lifecycle callbacks, native SQLite handling, or SQLCipher support; while the Kotlin module provides extension functions and reactive API integrations.
- The Test modules and Example projects are built on top of these components to showcase proper usage and verify system behavior.

##### Architectural Patterns and Design Principles
- Layered Architecture: Different layers separate the concerns – the annotation processing layer (code generation), the ORM core layer (entity mapping, caching, SQL DSL, database abstraction), and platform-specific layers for Android, Kotlin, and Jackson.
- Domain-Specific Language (DSL): The query language is built as a fluent, type-safe DSL that maps directly to SQL without the overhead of string concatenation.
- Compile-Time Code Generation vs. Reflection: A key design strategy is using compile time to generate high-performance entity code, which improves runtime performance and minimizes reflection.
- Reactive and Asynchronous Programming: Integration with RxJava and Java 8 streams makes it possible for the application to handle database operations reactively.

##### Relevant Technologies and Frameworks
- Java 8 functionalities (streams, optionals, new date/time APIs)
- Kotlin language features (property references, infix functions, and coroutines if applicable)
- RxJava for reactive programming
- SQL drivers for various databases (MySQL, Oracle, PostgreSQL, SQL Server, SQLite)
- Gradle as the build system (with scripts in build.gradle, gradlew, etc.)

- Top Layer: Client applications (example projects, tests) consuming the ORM API and writing queries.
- Middle Layer:
– Platform-specific wrappers (Android, Kotlin, Jackson) that adapt the core functionality.
– Core Library that houses the primary ORM logic (mapping, caching, query DSL, transaction handling).
- Bottom Layer:
– Annotation Processor generating code at compile time.
– External Dependencies & Drivers (RxJava, SQL drivers, external database systems).
- Clearly delineate the interactions; for example, show that the Annotation Processor feeds into the Core Library, while platform-specific modules extend or integrate with the Core Library.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Client Applications Subgraph
    subgraph "Client Applications"
        C1("Spring Boot Example"):::client
        C2("Android Example"):::client
        C3("Test Suites"):::client
    end

    %% Core and Platform Extensions Subgraph
    subgraph "Core and Platform Extensions"
        Core("Core Library (requery)"):::core
        AMod("Android Module (requery-android)"):::extension
        KMod("Kotlin Module (requery-kotlin)"):::extension
        JMod("Jackson Module (requery-jackson)"):::extension
    end

    %% Bottom Layer Subgraph
    subgraph "Annotation Processing & External Dependencies"
        Proc("Annotation Processor (requery-processor)"):::processor
        ED("External Dependencies (SQL Drivers, RxJava, etc)"):::external
    end

    %% Relationships
    Proc -->|"Generates"| Core
    ED -->|"Provides"| Core

    Core -->|"ExtendedBy"| AMod
    Core -->|"ExtendedBy"| KMod
    Core -->|"ExtendedBy"| JMod

    C1 -->|"Uses"| Core
    C2 -->|"Uses"| Core
    C3 -->|"Verifies"| Core

    %% Styles
    classDef core fill:#f4f9c9,stroke:#333,stroke-width:2px;
    classDef extension fill:#c9e4f4,stroke:#333,stroke-width:2px;
    classDef processor fill:#f9c9c9,stroke:#333,stroke-width:2px;
    classDef client fill:#c9f4c9,stroke:#333,stroke-width:2px;
    classDef external fill:#f4d9c9,stroke:#333,stroke-width:2px;

    %% Click Events
    click Core "https://github.com/jellybrick/requery-ng/tree/master/requery/src/main/java/io/requery"
    click Proc "https://github.com/jellybrick/requery-ng/tree/master/requery-processor/src/main/java/io/requery/processor"
    click AMod "https://github.com/jellybrick/requery-ng/tree/master/requery-android/src/main/java/io/requery/android"
    click KMod "https://github.com/jellybrick/requery-ng/tree/master/requery-kotlin/src/main/kotlin/io/requery"
    click JMod "https://github.com/jellybrick/requery-ng/tree/master/requery-jackson/src/main/java/io/requery/jackson"
    click C3 "https://github.com/jellybrick/requery-ng/tree/master/requery-test/src/main/java/io/requery/test"
    click C3 "https://github.com/jellybrick/requery-ng/tree/master/requery-test/kotlin-test/src/main/kotlin/io/requery/test"
    click C1 "https://github.com/jellybrick/requery-ng/tree/master/requery/example-springboot/src/main/java/io/requery/example/springboot"
    click C2 "https://github.com/jellybrick/requery-ng/tree/master/requery-android/example"
```
