Architecture

@biref/scanner uses a hexagonal (ports & adapters) architecture that separates database-specific logic from the paradigm-neutral core.

Layers

                   +-----------------------+
                   |     Your code         |
                   |  Biref.builder()...   |
                   +-----------+-----------+
                               |
                   +-----------v-----------+
                   |        Core           |
                   |  Biref, Scanner,      |
                   |  QueryPlanExecutor,   |
                   |  AdapterRegistry      |
                   +-----------+-----------+
                               |
              +----------------+----------------+
              |                                 |
   +----------v----------+          +-----------v-----------+
   |   Postgres Adapter   |          |    MySQL Adapter      |
   |   Introspector       |          |    Introspector       |
   |   QueryEngine        |          |    QueryEngine        |
   |   RawQueryRunner     |          |    RawQueryRunner     |
   |   RecordParser       |          |    RecordParser       |
   +----------+-----------+          +-----------+-----------+
              |                                 |
   +----------v----------+          +-----------v-----------+
   |     pg (driver)      |          |   mysql2 (driver)     |
   +----------------------+          +-----------------------+

Ports

Every adapter implements four ports:

Port	Responsibility
Introspector	Reads the database catalog and produces a DataModel
QueryEngine	Converts a QuerySpec into a parameterized SQL string
RawQueryRunner	Executes a BuiltQuery against the driver and returns raw rows
RecordParser	Coerces raw driver output into typed ParsedRecord values

Key types

Type	Description
Biref	Main facade. Holds the adapter registry, exposes scan() and query()
BirefBuilder	Fluent builder for configuring adapters
Adapter	A bundle of Introspector + QueryEngine + RawQueryRunner + RecordParser
AdapterFactory	Creates an Adapter from a driver client
DataModel	The scan result: all entities with relationships in both directions
QuerySpec	Paradigm-neutral query description (entity, select, filters, order, limit)
BuiltQuery	Engine output: SQL string + bound parameters
QueryPlan	Immutable tree built by the chain builder, one node per include level