# spaceshaman/ormagic architecture

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

- Interactive diagram: https://gitdiagram.com/spaceshaman/ormagic
- Repository: https://github.com/spaceshaman/ormagic

## Overview

##### Project Type and Purpose
- Recognize that the project is an open-source ORM library for Python. It abstracts database operations using Pydantic models.
- Its purpose is to offer an easy-to-use interface for CRUD operations, table management, enforcing relationships, transactions, and filtering, while supporting multiple backends (SQLite by default and PostgreSQL optionally).

##### File Structure to Identify the Main Components
- The core source code is in the "ormagic" directory. Key files include:
- __init__.py: Defines the module entry point.
- models.py: Likely contains the base model (DBModel) implementation that extends Pydantic.
- fields.py and field_utils.py: Responsible for field definitions and validation/helpers.
- query.py: Manages query building for filtering, sorting, and SQL operations.
- table_manager.py: Handles database table operations such as creation, updates, and deletion.
- transactions.py: Manages transactional operations.
- settings.py: Contains configuration logic (e.g., reading environment variables like ORMAGIC_DATABASE_URL) to determine database connections.
- The "ormagic/clients" folder contains:
- client.py: Maybe a base client abstraction.
- postgres.py and sqlite.py: Implementations to interact with PostgreSQL and SQLite respectively.
- The tests directory confirms comprehensive testing through various test cases ensuring all CRUD and SQL operations work as expected.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        UserCode("User Code / API Calls"):::appLayer
    end

    %% ORM Layer
    subgraph "ORM Layer"
        ORMCore("Base ORM Model (DBModel)"):::ormCore
        QueryBuilder("Query Builder"):::ormModule
        TableManager("Table Manager"):::ormModule
        FieldDefinitions("Field Definitions"):::ormModule
        FieldUtilities("Field Utilities"):::ormModule
        TransactionManager("Transaction Manager"):::ormModule
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        Settings("Configuration/Settings"):::configLayer
    end

    %% Database Layer
    subgraph "Database Layer"
        SQLite("SQLite Client"):::dbClient
        PostgreSQL("PostgreSQL Client"):::dbClient
    end

    %% Connections
    UserCode -->|"uses"| ORMCore
    ORMCore -->|"buildsQueries"| QueryBuilder
    ORMCore -->|"managesTables"| TableManager
    ORMCore -->|"mapsData"| FieldDefinitions
    ORMCore -->|"utilizes"| FieldUtilities
    TableManager -->|"initiates"| TransactionManager
    TransactionManager -->|"executesSQL"| SQLite
    TransactionManager -->|"executesSQL"| PostgreSQL
    Settings -->|"selectsClient"| SQLite
    Settings -->|"selectsClient"| PostgreSQL

    %% Click Events
    click ORMCore "https://github.com/spaceshaman/ormagic/blob/master/ormagic/models.py"
    click QueryBuilder "https://github.com/spaceshaman/ormagic/blob/master/ormagic/query.py"
    click TableManager "https://github.com/spaceshaman/ormagic/blob/master/ormagic/table_manager.py"
    click FieldDefinitions "https://github.com/spaceshaman/ormagic/blob/master/ormagic/fields.py"
    click FieldUtilities "https://github.com/spaceshaman/ormagic/blob/master/ormagic/field_utils.py"
    click TransactionManager "https://github.com/spaceshaman/ormagic/blob/master/ormagic/transactions.py"
    click SQLite "https://github.com/spaceshaman/ormagic/blob/master/ormagic/clients/sqlite.py"
    click PostgreSQL "https://github.com/spaceshaman/ormagic/blob/master/ormagic/clients/postgres.py"
    click Settings "https://github.com/spaceshaman/ormagic/blob/master/ormagic/settings.py"

    %% Styles
    classDef appLayer fill:#ffeb3b,stroke:#fbc02d,stroke-width:2px;
    classDef ormCore fill:#64b5f6,stroke:#1e88e5,stroke-width:2px;
    classDef ormModule fill:#90caf9,stroke:#42a5f5,stroke-width:2px;
    classDef configLayer fill:#ce93d8,stroke:#ab47bc,stroke-width:2px;
    classDef dbClient fill:#a5d6a7,stroke:#66bb6a,stroke-width:2px;
```
