# juliangomezortiz/peewee architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open-source Python ORM library (Peewee) plus an accompanying “playhouse” extensions package, example apps, CLI tools, docs and tests.
- Its purpose is to provide a small, expressive Active-Record style ORM supporting SQLite, MySQL/MariaDB, PostgreSQL and other backends via pluggable drivers and extensions.

##### High-Level Components
a. Core ORM Layer (peewee.py)
- Model definitions, Field types, Query Builder, Meta classes
- Database connection management and transaction API
b. Database Driver Adapters (playhouse/_pysqlite, _sqlite_ext, mysql_ext, psycopg3_ext, etc.)
- Low-level C/Python extensions for performance
- DB-specific compatibility shims
c. Playhouse Extensions Package (playhouse/)
- High-level add-ons: migrations, connection pools, KV Store, dataset API, signals, hybrid properties, Flask integration, etc.
d. CLI Tools
- pwiz.py (model code generator via database introspection)
- bench.py (benchmark suite)
- runtests.py (test runner wrapper)
e. Examples and Sample Apps (examples/)
- Demonstrations of using Peewee in different contexts (blog, analytics, Twitter clone)
f. Documentation (docs/)
- Sphinx source, HTML theme, API reference, tutorials
g. Test Suite (tests/)
- Unit and integration tests covering core, adapters, extensions, regressions

##### Component Relationships & Dataflow
- User application (examples or your own code) depends on Core ORM → defines Models → issues Query objects
- Core ORM sends SQL/commands to Database Driver Adapters → which invoke the native DB API
- Playhouse Extensions extend Core ORM classes or monkey-patch drivers to add specialized functionality (migration scripts, dataset API, encryption)
- CLI Tools import Core ORM + Adapters + Extensions to introspect or benchmark
- Tests import and validate all of the above
- Documentation references all modules but does not participate in runtime

##### Architectural Patterns & Principles
- Active Record: Models map directly to tables, queries built via chaining
- Separation of Concerns: Core ORM is independent of any one DB; adapters abstract DB internals; extensions live in a separate namespace
- Plugin/Extension Pattern: playhouse modules register new features via import hooks or subclassing
- Single Responsibility: pwiz only introspects and generates code, bench only runs benchmarks, runtests orchestrates test execution

##### Relevant Technologies & Frameworks
- Python 2.7+ / 3.4+
- Cython/C extensions for SQLite speedups
- DB drivers: sqlite3, APSW, psycopg2/psycopg3, MySQLdb, PyMySQL
- Sphinx for documentation
- Travis CI, GitHub Actions for CI tests
- setuptools / pyproject.toml for packaging

##### Capturing Essential Details
- Call out the plugin interface in playhouse (e.g., extension registration)
- Version compatibility across Python and DB backends
- How the packaging files (setup.py, pyproject.toml) tie everything together

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Tools & Examples
    subgraph "CLI Tools" 
        direction TB
        PWIZ["pwiz.py"]:::tool
        BENCH["bench.py"]:::tool
        RUNTESTS["runtests.py"]:::tool
    end
    subgraph "Example Apps" 
        direction TB
        EXAMPLES["examples/"]:::tool
    end

    %% Core ORM Layer
    PEWEE_CORE["peewee.py"]:::core

    %% Database Driver Adapters
    subgraph "Adapters" 
        direction TB
        PSQL2["playhouse/postgres_ext.py"]:::adapter
        PSYCOPG3["playhouse/psycopg3_ext.py"]:::adapter
        SQLITE_CPY["playhouse/_pysqlite/"]:::adapter
        SQLITE_EXT_PYX["playhouse/_sqlite_ext.pyx"]:::adapter
        SQLITE_UDF_PYX["playhouse/_sqlite_udf.pyx"]:::adapter
        SQLITE_PY_EXT["playhouse/sqlite_ext.py"]:::adapter
        SQLITE_PY_UDF["playhouse/sqlite_udf.py"]:::adapter
        SQLITEQ["playhouse/sqliteq.py"]:::adapter
        SQLITE_LOG["playhouse/sqlite_changelog.py"]:::adapter
        APSW["playhouse/apsw_ext.py"]:::adapter
        MYSQL["playhouse/mysql_ext.py"]:::adapter
        CROCK["playhouse/cockroachdb.py"]:::adapter
        SQLCIPHER["playhouse/sqlcipher_ext.py"]:::adapter
    end

    %% Playhouse Extensions
    subgraph "Playhouse Extensions" 
        direction TB
        PH_INIT["playhouse/__init__.py"]:::ext
        PH_README["playhouse/README.md"]:::ext
        MIGRATE["playhouse/migrate.py"]:::ext
        POOL["playhouse/pool.py"]:::ext
        DATASET["playhouse/dataset.py"]:::ext
        KV["playhouse/kv.py"]:::ext
        DBURL["playhouse/db_url.py"]:::ext
        FIELDS["playhouse/fields.py"]:::ext
        HYBRID["playhouse/hybrid.py"]:::ext
        FLASK["playhouse/flask_utils.py"]:::ext
        REFLECT["playhouse/reflection.py"]:::ext
        SHORTCUTS["playhouse/shortcuts.py"]:::ext
        SIGNALS["playhouse/signals.py"]:::ext
        TEST_UTILS["playhouse/test_utils.py"]:::ext
    end

    %% Packaging & CI
    subgraph "Packaging & CI"
        direction TB
        SETUP["setup.py"]:::dev
        PYPROJECT["pyproject.toml"]:::dev
        TRAVIS[".travis.yml"]:::dev
        GH_ACTIONS[".github/workflows/tests.yaml"]:::dev
        MANIFEST["MANIFEST.in"]:::dev
        LICENSE["LICENSE"]:::dev
        READMERST["README.rst"]:::dev
    end

    %% Documentation & Tests
    subgraph "Development" 
        direction TB
        DOCS["docs/"]:::dev
        TESTS["tests/"]:::dev
    end

    %% Relationships
    PWIZ -->|"imports"| PEWEE_CORE
    BENCH -->|"uses"| PEWEE_CORE
    RUNTESTS -->|"runs"| TESTS
    EXAMPLES -->|"uses"| PEWEE_CORE

    PEWEE_CORE -->|"execute_sql() calls"| SQLITE_CPY
    PEWEE_CORE -->|"execute_sql() calls"| APSW
    PEWEE_CORE -->|"execute_sql() calls"| PSQL2
    PEWEE_CORE -->|"execute_sql() calls"| PSYCOPG3
    PEWEE_CORE -->|"execute_sql() calls"| MYSQL
    PEWEE_CORE -->|"execute_sql() calls"| CROCK
    PEWEE_CORE -->|"execute_sql() calls"| SQLCIPHER

    PH_INIT -->|"extends"| PEWEE_CORE
    MIGRATE -->|"calls migrate()"| PEWEE_CORE
    POOL -->|"provides pool"| PEWEE_CORE
    DATASET -->|"provides dataset API"| PEWEE_CORE
    KV -->|"provides KV store"| PEWEE_CORE
    DBURL -->|"parses DB URLs"| PEWEE_CORE

    TESTS ---|tests| PEWEE_CORE
    TESTS ---|tests| APSW
    TESTS ---|tests| MIGRATE
    DOCS ---|docs| PEWEE_CORE
    DOCS ---|docs| PH_INIT

    PEWEE_CORE --> SETUP
    PEWEE_CORE --> PYPROJECT

    %% Click Events
    click PEWEE_CORE "https://github.com/juliangomezortiz/peewee/blob/master/peewee.py"
    click SQLITE_CPY "https://github.com/juliangomezortiz/peewee/tree/master/playhouse/_pysqlite/"
    click SQLITE_EXT_PYX "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/_sqlite_ext.pyx"
    click SQLITE_UDF_PYX "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/_sqlite_udf.pyx"
    click SQLITE_PY_EXT "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/sqlite_ext.py"
    click SQLITE_PY_UDF "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/sqlite_udf.py"
    click SQLITEQ "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/sqliteq.py"
    click SQLITE_LOG "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/sqlite_changelog.py"
    click APSW "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/apsw_ext.py"
    click PSQL2 "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/postgres_ext.py"
    click PSYCOPG3 "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/psycopg3_ext.py"
    click MYSQL "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/mysql_ext.py"
    click CROCK "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/cockroachdb.py"
    click SQLCIPHER "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/sqlcipher_ext.py"
    click PH_INIT "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/__init__.py"
    click PH_README "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/README.md"
    click MIGRATE "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/migrate.py"
    click POOL "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/pool.py"
    click DATASET "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/dataset.py"
    click KV "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/kv.py"
    click DBURL "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/db_url.py"
    click FIELDS "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/fields.py"
    click HYBRID "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/hybrid.py"
    click FLASK "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/flask_utils.py"
    click REFLECT "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/reflection.py"
    click SHORTCUTS "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/shortcuts.py"
    click SIGNALS "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/signals.py"
    click TEST_UTILS "https://github.com/juliangomezortiz/peewee/blob/master/playhouse/test_utils.py"
    click PWIZ "https://github.com/juliangomezortiz/peewee/blob/master/pwiz.py"
    click BENCH "https://github.com/juliangomezortiz/peewee/blob/master/bench.py"
    click RUNTESTS "https://github.com/juliangomezortiz/peewee/blob/master/runtests.py"
    click EXAMPLES "https://github.com/juliangomezortiz/peewee/tree/master/examples/"
    click DOCS "https://github.com/juliangomezortiz/peewee/tree/master/docs/"
    click TESTS "https://github.com/juliangomezortiz/peewee/tree/master/tests/"
    click SETUP "https://github.com/juliangomezortiz/peewee/blob/master/setup.py"
    click PYPROJECT "https://github.com/juliangomezortiz/peewee/blob/master/pyproject.toml"
    click TRAVIS "https://github.com/juliangomezortiz/peewee/blob/master/.travis.yml"
    click GH_ACTIONS "https://github.com/juliangomezortiz/peewee/blob/master/.github/workflows/tests.yaml"

    %% Styles
    classDef core fill:#a8d0e6,stroke:#1f618d,color:#1f618d;
    classDef adapter fill:#a3e4d7,stroke:#117864,color:#117864;
    classDef ext fill:#f5b041,stroke:#b9770e,color:#b9770e;
    classDef tool fill:#d7bde2,stroke:#6c3483,color:#6c3483,stroke-dasharray: 5 5;
    classDef dev fill:#d5d8dc,stroke:#566573,color:#566573;
```
