# tbiyiktas/android-sqlite-orm architecture

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

- Interactive diagram: https://gitdiagram.com/tbiyiktas/android-sqlite-orm
- Repository: https://github.com/tbiyiktas/android-sqlite-orm

## Overview

##### Project Type and Purpose
- This is an Android mobile application that demonstrates and bundles a lightweight Object-Relational Mapping (ORM) library for SQLite.
- The `app` module contains both a sample UI (`MainActivity`) and the full persistence library under `lib/persistence`.
- The ORM library provides annotation-based mapping, a generic repository API, builder-style queries, command objects, asynchronous callbacks, and clean-code separation.

##### File Structure Analysis
Top-level “app” module:
- `app/src/main/java/com/example/adbkit/MainActivity.java` → Presentation layer (Android UI).
- `app/src/main/java/lib/persistence/...` → Persistence library packages:
– `annotations` (mapping annotations)
– `command/definition`, `command/manipulation`, `command/query` (Command pattern for DDL/DML/queries)
– `domain/entities` (model classes, e.g., `Todo`, `Person`)
– `repositories` (concrete `TodoRepository`)
– `profile` (metadata, mappers)
– core classes: `ADbContext`, `GenericRepository`, `RepositoryFactory`, `DbCallback`, `DbResult`
- Resources: layouts, drawables, XML backup/data-extraction rules.
- Tests: unit and instrumentation tests for both UI and persistence.

##### README Insights
- ORM Features: annotation-based mapping, generic CRUD repository, fluent SelectQuery builder, asynchronous callbacks, clean architectures (SRP, DRY, DI).
- Usage: define model with `@DbTableAnnotation`/`@DbColumnAnnotation`, extend `ADbContext` for DB setup, extend `GenericRepository<T>` for model repos, then call `insert()`, `selectWhere()`, etc.

##### Main Components
a. Presentation Layer
- Android Activity/Fragment (MainActivity)
- Android UI framework (View, Layout XML)
b. Domain Layer
- Entity classes (`Todo`, `Person`)
c. Persistence Layer (ORM Library)
- Annotation Processor / Metadata Cache (`@DbTableAnnotation`, `@DbColumnAnnotation`, `RowMapper`, `Mapper`)
- Repository API (`GenericRepository<T>`, `TodoRepository`)
- DbContext (`ADbContext` subclass) → manages `SQLiteDatabase` lifecycle
- Command Objects
– DDL (CreateTableCommand, DropTableCommand, etc.)
– DML (InsertCommand, UpdateCommand, DeleteCommand)
– Query (SelectQuery, GetQuery)
- Callback mechanism (`DbCallback<T>`, `DbResult<T>`) for async operations
d. Data Store
- Android’s built-in `SQLiteDatabase` engine
e. External / Configuration
- ProGuard/R8 rules, Gradle build system, backup & data-extraction XML

##### Interactions and Data Flow
1. UI triggers an action (e.g., “Add Todo”) → calls into `TodoRepository.insert(...)`.
2. `TodoRepository` (extends `GenericRepository<Todo>`) builds an `InsertCommand` via repository internals.
3. `GenericRepository` delegates to `ADbContext` to get a writable `SQLiteDatabase`.
4. `ADbContext` constructs SQL (using metadata from annotations) and executes it on `SQLiteDatabase`.
5. Operation runs asynchronously on a background thread; result is returned via `DbCallback<DbResult<T>>`.
6. UI receives callback on success/failure and updates the view.

##### Architectural Patterns & Principles
- Repository Pattern: decouples data access from business logic/UI.
- Builder Pattern: `SelectQuery` fluent API for safe, parameterized queries.
- Command Pattern: encapsulates SQL operations in command objects.
- Dependency Injection: inject `ADbContext` into repositories via constructors.
- Clean Code: SRP (annotations vs. mapping vs. commands in separate packages), DRY (shared SQL utils), testability (interfaces, callbacks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        classDef presentation fill:#D6EAF8,stroke:#3498DB,color:#000;
        UI["MainActivity"]:::presentation
        Layout["activity_main.xml"]:::presentation
    end

    %% Domain Layer
    subgraph "Domain Layer"
        classDef domain fill:#D5F5E3,stroke:#27AE60,color:#000;
        Todo["Todo"]:::domain
        Person["Person"]:::domain
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        classDef persistence fill:#FDEBD0,stroke:#E67E22,color:#000;

        subgraph "Annotations"
            TableAnnot["@DbTableAnnotation"]:::persistence
            ColAnnot["@DbColumnAnnotation"]:::persistence
        end

        subgraph "Metadata/Profile"
            Mapper["Mapper"]:::persistence
            RowMapper["RowMapper"]:::persistence
            DbColumnProfile["DbColumn"]:::persistence
            DbDataType["DbDataType"]:::persistence
        end

        subgraph "Core"
            ADbContext["ADbContext"]:::persistence
            GenericRepo["GenericRepository<T>"]:::persistence
            RepoFactory["RepositoryFactory"]:::persistence
        end

        subgraph "Commands"
            classDef command fill:#FAD7A0,stroke:#D35400,color:#000;
            CreateTable["CreateTableCommand"]:::command
            DropTable["DropTableCommand"]:::command
            CreateIndex["CreateIndexCommand"]:::command
            DropIndex["DropIndexCommand"]:::command
            InsertCmd["InsertCommand"]:::command
            UpdateCmd["UpdateCommand"]:::command
            DeleteCmd["DeleteCommand"]:::command
            SelectQuery["SelectQuery"]:::command
            GetQuery["GetQuery"]:::command
            SelectMarker["Select"]:::command
        end

        TodoRepo["TodoRepository"]:::persistence

        subgraph "Callbacks"
            DbCallback["DbCallback<T>"]:::persistence
            DbResult["DbResult<T>"]:::persistence
        end
    end

    %% Data Store
    DataStore["SQLiteDatabase"]:::datastore

    %% External / Config
    subgraph "External / Config"
        classDef config fill:#E5E8E8,stroke:#95A5A6,color:#000;
        ProGuard["proguard-rules.pro"]:::config
        BackupXML["backup_rules.xml"]:::config
        DataExtrXML["data_extraction_rules.xml"]:::config
    end

    %% Relationships
    UI -->|uses layout| Layout
    UI -->|calls insert| TodoRepo
    TodoRepo -->|extends| GenericRepo
    TodoRepo -->|uses entity| Todo
    GenericRepo -->|injects| ADbContext
    ADbContext -->|executes| CreateTable
    ADbContext -->|executes| DropTable
    ADbContext -->|executes| CreateIndex
    ADbContext -->|executes| DropIndex
    ADbContext -->|executes| InsertCmd
    ADbContext -->|executes| UpdateCmd
    ADbContext -->|executes| DeleteCmd
    ADbContext -->|executes| SelectQuery
    ADbContext -->|executes| GetQuery
    CreateTable -->|builds SQL| DataStore
    DropTable -->|builds SQL| DataStore
    CreateIndex -->|builds SQL| DataStore
    DropIndex -->|builds SQL| DataStore
    InsertCmd -->|builds SQL| DataStore
    UpdateCmd -->|builds SQL| DataStore
    DeleteCmd -->|builds SQL| DataStore
    SelectQuery -->|builds SQL| DataStore
    GetQuery -->|builds SQL| DataStore
    DataStore -->|async result| DbResult
    DataStore -->|callback| DbCallback
    DbCallback -->|returns| UI

    Todo -->|annotated by| TableAnnot
    Todo -->|columns| ColAnnot
    TableAnnot -->|metadata| Mapper
    ColAnnot -->|metadata| RowMapper

    %% Click Events
    click UI "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/com/example/adbkit/MainActivity.java"
    click Layout "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/res/layout/activity_main.xml"
    click Todo "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/domain/entities/Todo.java"
    click Person "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/domain/entities/Person.java"
    click ADbContext "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/ADbContext.java"
    click GenericRepo "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/GenericRepository.java"
    click RepoFactory "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/RepositoryFactory.java"
    click DbCallback "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/DbCallback.java"
    click DbResult "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/DbResult.java"
    click TableAnnot "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/annotations/DbTableAnnotation.java"
    click ColAnnot "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/annotations/DbColumnAnnotation.java"
    click CreateTable "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/command/definition/CreateTableCommand.java"
    click DropTable "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/command/definition/DropTableCommand.java"
    click CreateIndex "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/command/definition/CreateIndexCommand.java"
    click DropIndex "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/command/definition/DropIndexCommand.java"
    click InsertCmd "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/command/manipulation/InsertCommand.java"
    click UpdateCmd "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/command/manipulation/UpdateCommand.java"
    click DeleteCmd "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/command/manipulation/DeleteCommand.java"
    click SelectQuery "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/command/query/SelectQuery.java"
    click GetQuery "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/command/query/GetQuery.java"
    click SelectMarker "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/command/query/Select.java"
    click Mapper "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/profile/Mapper.java"
    click RowMapper "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/profile/RowMapper.java"
    click DbColumnProfile "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/profile/DbColumn.java"
    click DbDataType "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/profile/DbDataType.java"
    click TodoRepo "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/java/lib/persistence/repositories/TodoRepository.java"
    click ProGuard "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/proguard-rules.pro"
    click BackupXML "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/res/xml/backup_rules.xml"
    click DataExtrXML "https://github.com/tbiyiktas/android-sqlite-orm/blob/main/app/src/main/res/xml/data_extraction_rules.xml"

    %% Styles
    classDef datastore fill:#D5D8DC,stroke:#7F8C8D,color:#000;
    classDef config fill:#E5E8E8,stroke:#95A5A6,color:#000;
    class PersistenceLayer command
    class UI,Layout presentation
    class Todo,Person domain
    class ADbContext,GenericRepo,RepoFactory,DbCallback,DbResult persistence
    class CreateTable,DropTable,CreateIndex,DropIndex,InsertCmd,UpdateCmd,DeleteCmd,SelectQuery,GetQuery,SelectMarker command
    class Mapper,RowMapper,DbColumnProfile,DbDataType persistence
    class ProGuard,BackupXML,DataExtrXML config
    class DataStore datastore
```
