# Architecture

This page shows in one overview diagram which layers make up `MySQLPool` and how they connect.

```mermaid
graph TB
    App[Application] --> Init["init()"]
    Init --> Cfg[Config Resolution<br/>object / env vars]
    Cfg --> RP[(Read Pool)]
    Cfg --> WP[(Write Pool)]
    App --> QB[Chainable Query Builder<br/>static state]
    App --> Raw["read() / write()"]
    QB --> Exec["query() Executor<br/>slow query log"]
    Raw --> Exec
    Exec --> RP
    Exec --> WP
```

## Layers

| Layer | Location | Responsibility |
|---|---|---|
| Config resolution | `init()`, `correctConfig()` (`src/MySQLPool.ts:40-97`) | Picks read and write configs by priority, fills defaults, creates and verifies `mysql2/promise` pools |
| Query builder | `table()` through `increase()` (`src/MySQLPool.ts:117-227`) | Accumulates columns, conditions, joins, sorting, and paging in static fields |
| SQL assembly | `get()`, `insert()`, `update()`, `upsert()` (`src/MySQLPool.ts:229-360`) | Turns the accumulated state into SQL and bindings |
| Executor | `query()` (`src/MySQLPool.ts:362-392`) | Picks the pool, checks out a connection, runs, times, and releases it |
| Raw entry points | `read()`, `write()` (`src/MySQLPool.ts:394-406`) | Run hand-written SQL on a fixed pool |
| Lifecycle | `close()` (`src/MySQLPool.ts:99-115`) | Close the pools |

## Cross-Cutting Principles

| Principle | Detail |
|---|---|
| Single database exit | Every SQL statement passes through `query()`, so slow query logging and connection release live in one place |
| Process-wide singleton | `MySQLPool` has only static members and a private constructor, so the whole process shares one pair of pools and one builder state |

## Further Reading

- Per-module diagrams, data flow, and state machine: [doc/architecture.md](https://github.com/pardnio/node-mysql-pool/blob/main/doc/architecture.md)
- [Read-Write Pools](/read-write-pools), [Builder State](/builder-state)