# msn560/phpwe architecture

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

- Interactive diagram: https://gitdiagram.com/msn560/phpwe
- Repository: https://github.com/msn560/phpwe

## Overview

##### Project type and purpose
- Type: Open-source PHP ORM framework (library).
- Purpose: Provide a lightweight, model-based abstraction over SQL databases with caching, unique constraints, and debugging.

##### File structure
- Top level:
- index.php – library entry point.
- composer.json – package metadata / autoload settings.
- config/ – host database configuration.
- src/ – core code:
– autoloader.php – PSR-4 autoloading.
– config.php – merges runtime config.
– database/ – all DB operations: cache, controllers, query builders, CRUD, relations, unique checks, debug hooks, base Model classes.
– models/ – user-defined entity classes (User, Session, Profile).
- docs/, examples/, test/ – usage guides, sample scripts, unit tests.

##### README for insights
- Stack: plain PHP, no external frameworks.
- Features: auto table creation/updates, relationships (hasOne, hasMany, belongsTo), caching, uniqueness, debug tools.
- Code flow: user code → Model classes → Database layer → underlying PDO/MySQL/SQLite.

##### Main components
A. Configuration
- config/config.php ← user edits DB credentials
- src/config.php ← loads config + environment
B. Autoloader
- src/autoloader.php → registers PSR-4 namespace resolution
C. Core Database Module (src/database)
1. Controllers – orchestrate CRUD
2. Query Builders – build SQL (query.php, insert/update/delete)
3. Model Base – src/database/model.php & model_query.php
4. Relations – one-to-one, one-to-many (relation.php)
5. Unique Constraint Handler (unique.php)
6. Cache Layer (cache.php)
7. Debug Tools (debug.php)
D. Domain Models (src/models)
- User, Session, Profile – extend Model base, annotate properties
E. Examples & Tests
- examples/ – sample usage flows (basic, cache, relations)
- test/ – unit/integration tests for user creation, etc.

##### Relationships & interactions
1. index.php → includes autoloader & config
2. User code → instantiates a Domain Model (e.g., new User())
3. Domain Model → calls Model::save()
4. Model::save() → invokes Controller → Query Builder
5. Query Builder → interfaces with Database Connection (PDO)
6. Before write → Unique.php for uniqueness checks
7. Optionally → Cache.php to cache results or queries
8. Debug.php can hook into any step to log SQL
9. Relations: Model::loadRelation() → Relation.php orchestrates JOINs/fetches

##### Architectural patterns & principles
- Active Record pattern (models wrap DB rows + behaviors)
- Single Responsibility: each class handles one aspect (query, cache, debug)
- PSR-4 Autoloading for modular code organization
- Separation of Concerns: config vs. core vs. user models vs. examples/tests

##### Final touches
- External dependency: PHP PDO extension or MySQL/SQLite engine.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Config & Entry"
        Index["index.php"]:::cfg
        ConfigUser["config/config.php"]:::cfg
        ConfigSrc["src/config.php"]:::cfg
        Autoloader["src/autoloader.php"]:::cfg
    end

    subgraph "Core Database Module"
        Controllers["Controllers<br>(controllers.php)"]:::core
        QueryBuilder["Query Builder<br>(query.php, insert.php, update.php, delete.php)"]:::core
        ModelBase["Model Base<br>(model.php, model_query.php)"]:::core
        Relations["Relations<br>(relation.php)"]:::core
        Unique["Unique Constraint<br>(unique.php)"]:::core
        Cache["Cache Layer<br>(cache.php)"]:::core
        Debug["Debug Tools<br>(debug.php)"]:::core
        DBDriver["Database Driver<br>(database.php)"]:::core
    end

    subgraph "Domain Models"
        UserModel["User<br>(user.php)"]:::ext
        SessionModel["Session<br>(session.php)"]:::ext
        ProfileModel["Profile<br>(profile.php)"]:::ext
    end

    subgraph "Examples & Tests"
        BasicExample["basic_example.php"]:::ext
        CacheExample["cache_example.php"]:::ext
        RelationExample["relation_example.php"]:::ext
        UserTest["user_create.php"]:::ext
    end

    PDO["PHP PDO Extension"]:::external

    %% Connections
    Index -->|includes| Autoloader
    Index -->|loads| ConfigSrc
    ConfigUser --> ConfigSrc

    Autoloader --> Controllers
    Autoloader --> ModelBase
    Autoloader --> QueryBuilder

    Index --> UserModel

    UserModel --> ModelBase
    SessionModel --> ModelBase
    ProfileModel --> ModelBase

    ModelBase --> Controllers
    Controllers --> QueryBuilder
    QueryBuilder --> DBDriver
    DBDriver --> PDO

    Controllers --> Unique
    Controllers --> Cache
    Controllers --> Debug

    ModelBase --> Relations
    Relations --> QueryBuilder

    BasicExample --> UserModel
    CacheExample --> UserModel
    RelationExample --> UserModel
    UserTest --> UserModel

    %% Click Events
    click ConfigUser "https://github.com/msn560/phpwe/blob/main/config/config.php"
    click ConfigSrc "https://github.com/msn560/phpwe/blob/main/src/config.php"
    click Autoloader "https://github.com/msn560/phpwe/blob/main/src/autoloader.php"
    click Index "https://github.com/msn560/phpwe/blob/main/index.php"
    click Controllers "https://github.com/msn560/phpwe/blob/main/src/database/controllers.php"
    click QueryBuilder "https://github.com/msn560/phpwe/blob/main/src/database/query.php"
    click QueryBuilder "https://github.com/msn560/phpwe/blob/main/src/database/insert.php"
    click QueryBuilder "https://github.com/msn560/phpwe/blob/main/src/database/update.php"
    click QueryBuilder "https://github.com/msn560/phpwe/blob/main/src/database/delete.php"
    click ModelBase "https://github.com/msn560/phpwe/blob/main/src/database/model.php"
    click ModelBase "https://github.com/msn560/phpwe/blob/main/src/database/model_query.php"
    click Relations "https://github.com/msn560/phpwe/blob/main/src/database/relation.php"
    click Unique "https://github.com/msn560/phpwe/blob/main/src/database/unique.php"
    click Cache "https://github.com/msn560/phpwe/blob/main/src/database/cache.php"
    click Debug "https://github.com/msn560/phpwe/blob/main/src/database/debug.php"
    click DBDriver "https://github.com/msn560/phpwe/blob/main/src/database/database.php"
    click UserModel "https://github.com/msn560/phpwe/blob/main/src/models/user.php"
    click SessionModel "https://github.com/msn560/phpwe/blob/main/src/models/session.php"
    click ProfileModel "https://github.com/msn560/phpwe/blob/main/src/models/profile.php"
    click BasicExample "https://github.com/msn560/phpwe/blob/main/examples/basic_example.php"
    click CacheExample "https://github.com/msn560/phpwe/blob/main/examples/cache_example.php"
    click RelationExample "https://github.com/msn560/phpwe/blob/main/examples/relation_example.php"
    click UserTest "https://github.com/msn560/phpwe/blob/main/test/user_create.php"
    click composer "https://github.com/msn560/phpwe/blob/main/composer.json"
    click readme "https://github.com/msn560/phpwe/blob/main/README.md"

    %% Styles
    classDef cfg fill:#FFE8A0,stroke:#D18B00,color:#D18B00
    classDef core fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef ext fill:#E6FFDA,stroke:#28A745,color:#28A745
    classDef external fill:#F2F2F2,stroke:#666,color:#333
```
