# coleifer/peewee architecture

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

- Interactive diagram: https://gitdiagram.com/coleifer/peewee
- Repository: https://github.com/coleifer/peewee

## Overview

Peewee is a compact Python ORM and SQL query builder. The principal workflow is application code defining models, composing queries, executing them through a database backend, and receiving mapped results. Model metadata is the key internal layer connecting declarations to SQL generation. Optional branches provide asyncio execution, SQLite full-text search, schema migration, database reflection/code generation, and framework/data-model integrations. The graph emphasizes documented capabilities and sampled runtime paths; some extension wiring is shown as optional where source excerpts were incomplete.

Main entry points: [`peewee.py`](https://github.com/coleifer/peewee/blob/master/peewee.py) (Database Runtime), [`playhouse/pwasyncio.py`](https://github.com/coleifer/peewee/blob/master/playhouse/pwasyncio.py) (Async Database API), [`playhouse`](https://github.com/coleifer/peewee/tree/master/playhouse) (Framework Adapters), [`playhouse/pydantic_utils.py`](https://github.com/coleifer/peewee/blob/master/playhouse/pydantic_utils.py) (Pydantic Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core ORM"]
  node_model_api["Model API<br/>[peewee.py]"]
  node_metadata["Model Metadata<br/>[peewee.py]"]
  node_query_builder["Query Builder<br/>[peewee.py]"]
  node_result_mapping["Result Mapping<br/>[peewee.py]"]
end

subgraph group_storage["Database Runtime"]
  node_database_runtime["Database Runtime<br/>[peewee.py]"]
  node_sqlite_db[("SQLite Database")]
  node_mysql_db[("MySQL Database")]
  node_postgres_db[("PostgreSQL Database")]
end

subgraph group_extensions["Runtime Extensions"]
  node_async_api["Async Database API<br/>[pwasyncio.py]"]
  node_async_drivers["Async Drivers"]
  node_fts_extension["SQLite FTS<br/>[sqlite_ext.py]"]
  node_fts_parser["FTS Query Parser<br/>[fts_parser.py]"]
  node_framework_adapters["Framework Adapters"]
  node_pydantic_adapter["Pydantic Adapter<br/>[pydantic_utils.py]"]
end

subgraph group_tooling["Schema Tooling"]
  node_migration_runner["Migration Runner<br/>[migrations.py]"]
  node_schema_migrator["Schema Migrator<br/>[migrate.py]"]
  node_reflection["Database Reflection<br/>[reflection.py]"]
  node_pwiz["Model Generator<br/>[pwiz.py]"]
end

node_developer(("Application Developer"))

node_developer -->|"defines models"| node_model_api
node_model_api -->|"registers fields"| node_metadata
node_metadata -->|"describes models"| node_query_builder
node_developer -->|"builds queries"| node_query_builder
node_query_builder -->|"executes SQL"| node_database_runtime
node_database_runtime -->|"sends SQL"| node_sqlite_db
node_database_runtime -.->|"sends SQL"| node_mysql_db
node_database_runtime -.->|"sends SQL"| node_postgres_db
node_database_runtime -->|"returns cursors"| node_result_mapping
node_result_mapping -->|"returns models"| node_developer
node_developer -->|"awaits queries"| node_async_api
node_async_api -->|"uses drivers"| node_async_drivers
node_async_api -->|"buffers results"| node_result_mapping
node_developer -.->|"searches text"| node_fts_extension
node_fts_parser -.->|"produces query"| node_fts_extension
node_developer -->|"runs migrations"| node_migration_runner
node_migration_runner -->|"runs operations"| node_schema_migrator
node_schema_migrator -->|"executes DDL"| node_database_runtime
node_developer -->|"generates models"| node_pwiz
node_pwiz -->|"inspects schema"| node_reflection
node_reflection -->|"reads metadata"| node_database_runtime
node_developer -.->|"integrates apps"| node_framework_adapters
node_framework_adapters -.->|"uses ORM"| node_model_api
node_developer -.->|"serializes models"| node_pydantic_adapter
node_pydantic_adapter -.->|"reads models"| node_model_api

click node_model_api "https://github.com/coleifer/peewee/blob/master/peewee.py"
click node_metadata "https://github.com/coleifer/peewee/blob/master/peewee.py"
click node_query_builder "https://github.com/coleifer/peewee/blob/master/peewee.py"
click node_result_mapping "https://github.com/coleifer/peewee/blob/master/peewee.py"
click node_database_runtime "https://github.com/coleifer/peewee/blob/master/peewee.py"
click node_async_api "https://github.com/coleifer/peewee/blob/master/playhouse/pwasyncio.py"
click node_fts_extension "https://github.com/coleifer/peewee/blob/master/playhouse/sqlite_ext.py"
click node_fts_parser "https://github.com/coleifer/peewee/blob/master/playhouse/fts_parser.py"
click node_migration_runner "https://github.com/coleifer/peewee/blob/master/playhouse/migrations.py"
click node_schema_migrator "https://github.com/coleifer/peewee/blob/master/playhouse/migrate.py"
click node_reflection "https://github.com/coleifer/peewee/blob/master/playhouse/reflection.py"
click node_pwiz "https://github.com/coleifer/peewee/blob/master/pwiz.py"
click node_framework_adapters "https://github.com/coleifer/peewee/tree/master/playhouse"
click node_pydantic_adapter "https://github.com/coleifer/peewee/blob/master/playhouse/pydantic_utils.py"

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_model_api,node_metadata,node_query_builder,node_result_mapping toneBlue
class node_database_runtime,node_sqlite_db,node_mysql_db,node_postgres_db toneAmber
class node_async_api,node_async_drivers,node_fts_extension,node_fts_parser,node_framework_adapters,node_pydantic_adapter toneMint
class node_migration_runner,node_schema_migrator,node_reflection,node_pwiz toneRose
class node_developer toneIndigo
```

## Components

### Core ORM

- [Model API](https://github.com/coleifer/peewee/blob/master/peewee.py): `peewee.py`
- [Model Metadata](https://github.com/coleifer/peewee/blob/master/peewee.py): `peewee.py`
- [Query Builder](https://github.com/coleifer/peewee/blob/master/peewee.py): `peewee.py`
- [Result Mapping](https://github.com/coleifer/peewee/blob/master/peewee.py): `peewee.py`

### Database Runtime

- [Database Runtime](https://github.com/coleifer/peewee/blob/master/peewee.py): `peewee.py`
- **SQLite Database**
- **MySQL Database**
- **PostgreSQL Database**

### Runtime Extensions

- [Async Database API](https://github.com/coleifer/peewee/blob/master/playhouse/pwasyncio.py): `playhouse/pwasyncio.py`
- **Async Drivers**
- [SQLite FTS](https://github.com/coleifer/peewee/blob/master/playhouse/sqlite_ext.py): `playhouse/sqlite_ext.py`
- [FTS Query Parser](https://github.com/coleifer/peewee/blob/master/playhouse/fts_parser.py): `playhouse/fts_parser.py`
- [Framework Adapters](https://github.com/coleifer/peewee/tree/master/playhouse): `playhouse`
- [Pydantic Adapter](https://github.com/coleifer/peewee/blob/master/playhouse/pydantic_utils.py): `playhouse/pydantic_utils.py`

### Schema Tooling

- [Migration Runner](https://github.com/coleifer/peewee/blob/master/playhouse/migrations.py): `playhouse/migrations.py`
- [Schema Migrator](https://github.com/coleifer/peewee/blob/master/playhouse/migrate.py): `playhouse/migrate.py`
- [Database Reflection](https://github.com/coleifer/peewee/blob/master/playhouse/reflection.py): `playhouse/reflection.py`
- [Model Generator](https://github.com/coleifer/peewee/blob/master/pwiz.py): `pwiz.py`

### Other components

- **Application Developer**

## Connections

- Application Developer → Model API: defines models
- Model API → Model Metadata: registers fields
- Model Metadata → Query Builder: describes models
- Application Developer → Query Builder: builds queries
- Query Builder → Database Runtime: executes SQL
- Database Runtime → SQLite Database: sends SQL
- Database Runtime → MySQL Database: sends SQL
- Database Runtime → PostgreSQL Database: sends SQL
- Database Runtime → Result Mapping: returns cursors
- Result Mapping → Application Developer: returns models
- Application Developer → Async Database API: awaits queries
- Async Database API → Async Drivers: uses drivers
- Async Database API → Result Mapping: buffers results
- Application Developer → SQLite FTS: searches text
- FTS Query Parser → SQLite FTS: produces query
- Application Developer → Migration Runner: runs migrations
- Migration Runner → Schema Migrator: runs operations
- Schema Migrator → Database Runtime: executes DDL
- Application Developer → Model Generator: generates models
- Model Generator → Database Reflection: inspects schema
- Database Reflection → Database Runtime: reads metadata
- Application Developer → Framework Adapters: integrates apps
- Framework Adapters → Model API: uses ORM
- Application Developer → Pydantic Adapter: serializes models
- Pydantic Adapter → Model API: reads models
