Core vs. User-Land Boundary
- Introduction
- The Boundary Architecture
- The Golden Rules of Reyhan Development
- How Customizations Stay Intact
- The Upgrade Safety Guarantee
Introduction
The primary architectural strength of Reyhan Commerce is the clean, unyielding separation between the Framework Core Package (reyhan-commerce/core) and your User-Land Store Application (app/, config/, extensions/).
In legacy e-commerce software, developers routinely modify core controllers, database seeders, or vendor files. When upstream maintainers release security patches or major feature updates, running updates results in merge conflicts, broken logic, and costly manual refactors.
Reyhan permanently eliminates this problem through clean Composer encapsulation, interface contracts, and dynamic runtime bindings.
The Boundary Architecture
┌─────────────────────────────────────────────────────────────┐
│ reyhan-commerce/core (Vendor Package) │
│ - Immutable e-commerce engine │
│ - Standard REST API contracts & routes (/api/v1) │
│ - Base models, migrations & Filament admin plugin │
│ - Upgraded cleanly via: composer update │
└──────────────────────────────┬──────────────────────────────┘
│
Overrides & Extends via Clean Contracts
▼
┌─────────────────────────────────────────────────────────────┐
│ User-Land Application (Your Store Code) │
│ - app/Models/ (Custom models via Reyhan::useModel) │
│ - extensions/ (Custom modular plugins & drivers) │
│ - app/Actions/ (Custom user-land business workflows) │
│ - config/reyhan.php (Runtime configuration overrides) │
└─────────────────────────────────────────────────────────────┘The Golden Rules of Reyhan Development
To ensure your application remains clean, maintainable, and continuously upgradable, adhere to the following rules:
Rule 1: Never Touch Vendor Files
Never edit files inside vendor/reyhan-commerce/core/. When you need to customize behavior:
- Add custom columns or methods to models: Extend the base model in
app/Models/and register it inconfig/reyhan.php. Read the Extending Models Guide. - Add a custom payment driver: Implement
GatewayDriverContractand register it viaPayment::extend(). Read the Payment Gateways Guide. - Add specialized business logic: Create a single-responsibility Action class in
app/Actions/. - Add modular features: Place them in
extensions/{plugin-name}/. Read the Modular Extensions Guide.
Rule 2: Decoupled Storefront Independence
The frontend presentation layer (such as the official Nuxt 4 storefront) is fully decoupled. It communicates with the backend exclusively through RESTful JSON APIs and WebSocket channels. Frontend updates never risk destabilizing the backend business logic or database schema.
How Customizations Stay Intact
Because all core services resolve classes through dynamic registries (Reyhan::model(), Reyhan::payment(), Pipeline::through()), your custom classes seamlessly intercept all domain traffic:
// Your custom logic executes in place of core defaults
$orderModel = Reyhan::model('order'); // Resolves App\Models\CustomOrderThe Upgrade Safety Guarantee
Upgrading your store's core engine is as simple as running:
./reyhan update
# or
composer update reyhan-commerce/core --with-all-dependencies
php artisan migrate --force
php artisan reyhan:doctorThis guarantees:
- Zero Merge Conflicts: Core framework improvements are pulled cleanly without touching your repository's files.
- Deterministic Migrations: Database schema updates execute idempotently.
- Continuous Compatibility: Your custom models, pipelines, and extensions remain completely intact.