# qicosmos/ormpp architecture

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

- Interactive diagram: https://gitdiagram.com/qicosmos/ormpp
- Repository: https://github.com/qicosmos/ormpp

## Overview

ormpp is a header-only C++ ORM that presents a common API for mapping C++ entities to SQLite, MySQL, or PostgreSQL and performing database operations. The principal workflow is to register an entity, connect through the ORM facade, build or invoke an operation, and receive mapped results. Its documented capabilities also include connection pools, async MySQL, AOP, and SQLite encryption. The tree includes Iguana serialization formats; their runtime wiring to ormpp is not established by the sampled excerpts, so they are shown as a separate capability. Some internal implementation links are omitted where excerpts do not establish callers.

Main entry points: [`ormpp/dbng.hpp`](https://github.com/qicosmos/ormpp/blob/master/ormpp/dbng.hpp) (ORM facade), [`iguana/iguana.hpp`](https://github.com/qicosmos/ormpp/blob/master/iguana/iguana.hpp) (Iguana serialization), [`ormpp/sqlite.hpp`](https://github.com/qicosmos/ormpp/blob/master/ormpp/sqlite.hpp) (SQLite adapter), [`ormpp/mysql_async.hpp`](https://github.com/qicosmos/ormpp/blob/master/ormpp/mysql_async.hpp) (Async MySQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orm["ORM API"]
  node_facade["ORM facade<br/>[dbng.hpp]"]
  node_entity["Entity mapping<br/>[entity.hpp]"]
  node_query["Typed query builder<br/>[query.hpp]"]
end

subgraph group_db["Database adapters"]
  node_mysql["MySQL adapter<br/>[mysql.hpp]"]
  node_postgres["PostgreSQL adapter<br/>[postgresql.hpp]"]
  node_sqlite["SQLite adapter<br/>[sqlite.hpp]"]
end

subgraph group_infra["Connection management"]
  node_pool["Connection pools"]
  node_async_pool["Async connections"]
  node_async_mysql["Async MySQL<br/>[mysql_async.hpp]"]
  node_aop["AOP hooks<br/>[dbng.hpp]"]
  node_cipher["SQLite encryption<br/>[sqlite.hpp]"]
end

subgraph group_serial["Serialization"]
  node_iguana["Iguana serialization<br/>[iguana.hpp]"]
  node_json["JSON reader/writer<br/>[json_reader.hpp]"]
  node_xml["XML reader/writer<br/>[xml_reader.hpp]"]
  node_yaml["YAML reader/writer<br/>[yaml_reader.hpp]"]
  node_protobuf["Protobuf reader/writer<br/>[pb_reader.hpp]"]
end

node_developer(("C++ application"))
node_mysql_service[("MySQL database")]
node_postgres_service[("PostgreSQL database")]
node_sqlite_service[("SQLite database")]

node_developer -->|"calls API"| node_facade
node_facade -->|"maps entities"| node_entity
node_facade -->|"builds queries"| node_query
node_facade -->|"dispatches operations"| node_mysql
node_facade -->|"dispatches operations"| node_postgres
node_facade -->|"dispatches operations"| node_sqlite
node_mysql -->|"executes SQL"| node_mysql_service
node_postgres -->|"executes SQL"| node_postgres_service
node_sqlite -->|"executes SQL"| node_sqlite_service
node_facade -->|"uses connections"| node_pool
node_async_mysql -->|"uses connections"| node_async_pool
node_async_mysql -->|"queries asynchronously"| node_mysql_service
node_facade -.->|"accepts hooks"| node_aop
node_sqlite -.->|"supports encryption"| node_cipher
node_iguana -->|"provides format"| node_json
node_iguana -->|"provides format"| node_xml
node_iguana -->|"provides format"| node_yaml
node_iguana -->|"provides format"| node_protobuf

click node_facade "https://github.com/qicosmos/ormpp/blob/master/ormpp/dbng.hpp"
click node_entity "https://github.com/qicosmos/ormpp/blob/master/ormpp/entity.hpp"
click node_query "https://github.com/qicosmos/ormpp/blob/master/ormpp/query.hpp"
click node_mysql "https://github.com/qicosmos/ormpp/blob/master/ormpp/mysql.hpp"
click node_postgres "https://github.com/qicosmos/ormpp/blob/master/ormpp/postgresql.hpp"
click node_sqlite "https://github.com/qicosmos/ormpp/blob/master/ormpp/sqlite.hpp"
click node_pool "https://github.com/qicosmos/ormpp/blob/master/ormpp/connection_pool.hpp"
click node_async_pool "https://github.com/qicosmos/ormpp/blob/master/ormpp/async_connection_pool.hpp"
click node_async_mysql "https://github.com/qicosmos/ormpp/blob/master/ormpp/mysql_async.hpp"
click node_aop "https://github.com/qicosmos/ormpp/blob/master/ormpp/dbng.hpp"
click node_cipher "https://github.com/qicosmos/ormpp/blob/master/ormpp/sqlite.hpp"
click node_iguana "https://github.com/qicosmos/ormpp/blob/master/iguana/iguana.hpp"
click node_json "https://github.com/qicosmos/ormpp/blob/master/iguana/json_reader.hpp"
click node_xml "https://github.com/qicosmos/ormpp/blob/master/iguana/xml_reader.hpp"
click node_yaml "https://github.com/qicosmos/ormpp/blob/master/iguana/yaml_reader.hpp"
click node_protobuf "https://github.com/qicosmos/ormpp/blob/master/iguana/pb_reader.hpp"

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_facade,node_entity,node_query toneBlue
class node_mysql,node_postgres,node_sqlite,node_mysql_service,node_postgres_service,node_sqlite_service toneAmber
class node_pool,node_async_pool,node_async_mysql,node_aop,node_cipher toneMint
class node_iguana,node_json,node_xml,node_yaml,node_protobuf toneRose
class node_developer toneIndigo
```

## Components

### ORM API

- [ORM facade](https://github.com/qicosmos/ormpp/blob/master/ormpp/dbng.hpp): `ormpp/dbng.hpp`
- [Entity mapping](https://github.com/qicosmos/ormpp/blob/master/ormpp/entity.hpp): `ormpp/entity.hpp`
- [Typed query builder](https://github.com/qicosmos/ormpp/blob/master/ormpp/query.hpp): `ormpp/query.hpp`

### Database adapters

- [MySQL adapter](https://github.com/qicosmos/ormpp/blob/master/ormpp/mysql.hpp): `ormpp/mysql.hpp`
- [PostgreSQL adapter](https://github.com/qicosmos/ormpp/blob/master/ormpp/postgresql.hpp): `ormpp/postgresql.hpp`
- [SQLite adapter](https://github.com/qicosmos/ormpp/blob/master/ormpp/sqlite.hpp): `ormpp/sqlite.hpp`

### Connection management

- [Connection pools](https://github.com/qicosmos/ormpp/blob/master/ormpp/connection_pool.hpp): `ormpp/connection_pool.hpp`
- [Async connections](https://github.com/qicosmos/ormpp/blob/master/ormpp/async_connection_pool.hpp): `ormpp/async_connection_pool.hpp`
- [Async MySQL](https://github.com/qicosmos/ormpp/blob/master/ormpp/mysql_async.hpp): `ormpp/mysql_async.hpp`
- [AOP hooks](https://github.com/qicosmos/ormpp/blob/master/ormpp/dbng.hpp): `ormpp/dbng.hpp`
- [SQLite encryption](https://github.com/qicosmos/ormpp/blob/master/ormpp/sqlite.hpp): `ormpp/sqlite.hpp`

### Serialization

- [Iguana serialization](https://github.com/qicosmos/ormpp/blob/master/iguana/iguana.hpp): `iguana/iguana.hpp`
- [JSON reader/writer](https://github.com/qicosmos/ormpp/blob/master/iguana/json_reader.hpp): `iguana/json_reader.hpp`
- [XML reader/writer](https://github.com/qicosmos/ormpp/blob/master/iguana/xml_reader.hpp): `iguana/xml_reader.hpp`
- [YAML reader/writer](https://github.com/qicosmos/ormpp/blob/master/iguana/yaml_reader.hpp): `iguana/yaml_reader.hpp`
- [Protobuf reader/writer](https://github.com/qicosmos/ormpp/blob/master/iguana/pb_reader.hpp): `iguana/pb_reader.hpp`

### Other components

- **C++ application**
- **MySQL database**
- **PostgreSQL database**
- **SQLite database**

## Connections

- C++ application → ORM facade: calls API
- ORM facade → Entity mapping: maps entities
- ORM facade → Typed query builder: builds queries
- ORM facade → MySQL adapter: dispatches operations
- ORM facade → PostgreSQL adapter: dispatches operations
- ORM facade → SQLite adapter: dispatches operations
- MySQL adapter → MySQL database: executes SQL
- PostgreSQL adapter → PostgreSQL database: executes SQL
- SQLite adapter → SQLite database: executes SQL
- ORM facade → Connection pools: uses connections
- Async MySQL → Async connections: uses connections
- Async MySQL → MySQL database: queries asynchronously
- ORM facade → AOP hooks: accepts hooks
- SQLite adapter → SQLite encryption: supports encryption
- Iguana serialization → JSON reader/writer: provides format
- Iguana serialization → XML reader/writer: provides format
- Iguana serialization → YAML reader/writer: provides format
- Iguana serialization → Protobuf reader/writer: provides format