# ahmatfauzy/pawql-orm architecture

> Architecture diagram of the GitHub repository ahmatfauzy/pawql-orm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmatfauzy/pawql-orm
- Repository: https://github.com/ahmatfauzy/pawql-orm

## Overview

PawQL is a runtime-schema TypeScript ORM and SQL query builder. An application supplies a schema and database connection, creates a database instance, builds typed queries, and executes them through a dialect adapter against a database. Distinct runtime capabilities include query construction, adapter execution, schema-based table creation, migrations, introspection, validation, seeding, relations, hooks, and telemetry. The main database/query-builder and adapter execution paths are supported by sampled source; several additional capabilities are documented or exported, but their internal call wiring was not sampled.

Main entry points: [`src/core/database.ts`](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/database.ts) (Database), [`src/core/adapter.ts`](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/adapter.ts) (Adapter Contract), [`src/query/builder.ts`](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/query/builder.ts) (Query Builder), [`src/types/schema.ts`](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/types/schema.ts) (Runtime Schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Schema and API"]
  node_schema["Runtime Schema<br/>[schema.ts]"]
  node_public["Public API<br/>[index.ts]"]
  node_database["Database<br/>[database.ts]"]
end

subgraph group_queries["Query Runtime"]
  node_builder["Query Builder<br/>[builder.ts]"]
  node_relations["Relations<br/>[relations.ts]"]
  node_hooks["Hooks<br/>[hooks.ts]"]
  node_validator["Row Validation<br/>[validator.ts]"]
end

subgraph group_storage["Database Adapters"]
  node_adapter_contract["Adapter Contract<br/>[adapter.ts]"]
  node_postgres["PostgreSQL Adapter<br/>[pg.ts]"]
  node_mysql["MySQL Adapter<br/>[mysql.ts]"]
  node_sqlite["SQLite Adapter<br/>[sqlite.ts]"]
end

subgraph group_operations["Database Operations"]
  node_ddl["Table Creation<br/>[database.ts]"]
  node_migrations["Migrations"]
  node_introspection["Introspection<br/>[introspect.ts]"]
  node_seeders["Seeders<br/>[seeder.ts]"]
  node_telemetry["Telemetry Plugin<br/>[telemetry.ts]"]
  node_logger["Logger<br/>[logger.ts]"]
end

node_application(("Application"))
node_database_service[("Database Service")]
node_query_result["Query Results"]

node_application -->|"imports"| node_public
node_application -->|"defines"| node_schema
node_application -->|"creates"| node_database
node_public -->|"exports"| node_database
node_schema -->|"configures"| node_database
node_database -->|"creates"| node_builder
node_database -->|"uses"| node_adapter_contract
node_database -->|"creates tables"| node_ddl
node_database -->|"configures"| node_relations
node_database -->|"configures"| node_hooks
node_database -->|"wraps adapter"| node_logger
node_builder -->|"executes SQL"| node_adapter_contract
node_builder -->|"resolves joins"| node_relations
node_builder -->|"runs hooks"| node_hooks
node_adapter_contract -->|"implemented by"| node_postgres
node_adapter_contract -->|"implemented by"| node_mysql
node_adapter_contract -->|"implemented by"| node_sqlite
node_postgres -->|"queries"| node_database_service
node_mysql -->|"queries"| node_database_service
node_sqlite -->|"queries"| node_database_service
node_database_service -->|"returns rows"| node_query_result
node_application -->|"validates data"| node_validator
node_application -->|"runs migrations"| node_migrations
node_application -->|"requests schema"| node_introspection
node_introspection -->|"queries metadata"| node_adapter_contract
node_application -->|"seeds data"| node_seeders
node_application -.->|"installs plugin"| node_telemetry

click node_schema "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/types/schema.ts"
click node_public "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/index.ts"
click node_database "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/database.ts"
click node_builder "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/query/builder.ts"
click node_relations "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/relations.ts"
click node_hooks "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/hooks.ts"
click node_validator "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/validator.ts"
click node_adapter_contract "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/adapter.ts"
click node_postgres "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/adapters/pg.ts"
click node_mysql "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/adapters/mysql.ts"
click node_sqlite "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/adapters/sqlite.ts"
click node_ddl "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/database.ts"
click node_migrations "https://github.com/ahmatfauzy/pawql-orm/tree/main/src/migration"
click node_introspection "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/introspect.ts"
click node_seeders "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/seeder.ts"
click node_telemetry "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/plugins/telemetry.ts"
click node_logger "https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/logger.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_schema,node_public,node_database toneBlue
class node_builder,node_relations,node_hooks,node_validator,node_database_service toneAmber
class node_adapter_contract,node_postgres,node_mysql,node_sqlite toneMint
class node_ddl,node_migrations,node_introspection,node_seeders,node_telemetry,node_logger toneRose
class node_application,node_query_result toneIndigo
```

## Components

### Schema and API

- [Runtime Schema](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/types/schema.ts): `src/types/schema.ts`
- [Public API](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/index.ts): `src/index.ts`
- [Database](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/database.ts): `src/core/database.ts`

### Query Runtime

- [Query Builder](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/query/builder.ts): `src/query/builder.ts`
- [Relations](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/relations.ts): `src/core/relations.ts`
- [Hooks](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/hooks.ts): `src/core/hooks.ts`
- [Row Validation](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/validator.ts): `src/core/validator.ts`

### Database Adapters

- [Adapter Contract](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/adapter.ts): `src/core/adapter.ts`
- [PostgreSQL Adapter](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/adapters/pg.ts): `src/adapters/pg.ts`
- [MySQL Adapter](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/adapters/mysql.ts): `src/adapters/mysql.ts`
- [SQLite Adapter](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/adapters/sqlite.ts): `src/adapters/sqlite.ts`

### Database Operations

- [Table Creation](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/database.ts): `src/core/database.ts`
- [Migrations](https://github.com/ahmatfauzy/pawql-orm/tree/main/src/migration): `src/migration`
- [Introspection](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/introspect.ts): `src/core/introspect.ts`
- [Seeders](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/seeder.ts): `src/core/seeder.ts`
- [Telemetry Plugin](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/plugins/telemetry.ts): `src/plugins/telemetry.ts`
- [Logger](https://github.com/ahmatfauzy/pawql-orm/blob/main/src/core/logger.ts): `src/core/logger.ts`

### Other components

- **Application**
- **Database Service**
- **Query Results**

## Connections

- Application → Public API: imports
- Application → Runtime Schema: defines
- Application → Database: creates
- Public API → Database: exports
- Runtime Schema → Database: configures
- Database → Query Builder: creates
- Database → Adapter Contract: uses
- Database → Table Creation: creates tables
- Database → Relations: configures
- Database → Hooks: configures
- Database → Logger: wraps adapter
- Query Builder → Adapter Contract: executes SQL
- Query Builder → Relations: resolves joins
- Query Builder → Hooks: runs hooks
- Adapter Contract → PostgreSQL Adapter: implemented by
- Adapter Contract → MySQL Adapter: implemented by
- Adapter Contract → SQLite Adapter: implemented by
- PostgreSQL Adapter → Database Service: queries
- MySQL Adapter → Database Service: queries
- SQLite Adapter → Database Service: queries
- Database Service → Query Results: returns rows
- Application → Row Validation: validates data
- Application → Migrations: runs migrations
- Application → Introspection: requests schema
- Introspection → Adapter Contract: queries metadata
- Application → Seeders: seeds data
- Application → Telemetry Plugin: installs plugin