1 · The decision rule

TL;DR

Objective — before you change anything, answer three questions that route the change to the right update-safe home, so the next vendor update never overwrites your work.

User part + done-when

👤 User part — this is a thinking step, not a clicking step: a person reads the change request and decides which of the three homes it belongs in. No dashboards, no passwords.

Done when you can name, for your change, whether it is a ZajModule, a vendor customization, or a _zaj migration — and why.  ·  ⏱ ~5 min  ·  👤 user decision.

Background

A CodeCanyon app’s code is the vendor’s, not yours. Every time you edit a vendor file in place, the next release fights you for it — merge conflicts, lost work, hours of re-debugging. The whole methodology exists to avoid that: send every change to a home the vendor never touches.

There are exactly three homes, and one question decides each. Get the routing right once and updates become a non-event.

Steps

1. Ask: am I adding something new, or editing something that exists?

This is the first and biggest fork. New functionality should never live inside vendor files — it gets its own package.

1. If the change is brand-new functionality — a new integration, a new feature, a new admin tool — build it as a ZajModule package under packages/ZajModules/{Type}/{Category}/{Name}/. The vendor app never references it, so vendor updates pass straight through.

   • ✅ The feature lives entirely in its own folder; no vendor file was touched.

2. If the change edits an existing vendor file — and only because no event hook or override can do the job — it becomes a vendor customization (next question).

   • ✅ You have confirmed an event-driven approach genuinely won’t work before reaching for a vendor edit.

Try event-driven first

Most “edits” aren’t really needed. Laravel fires events for registration, login, payment, and more — a ZajModule can listen to those instead of editing the controller that triggers them. Reach for a vendor edit only when the vendor’s logic is hardcoded with no hook to listen to.

2. Ask: does this edit live in a vendor file I can’t avoid touching?

Some vendor logic is tightly coupled — a hardcoded path scan, a flawed calculation with no override point. When there’s truly no alternative, you edit the file, but you store the edited copy where updates can’t erase it.

1. Put the edited copy in the overlay at resources/vendor-customizations/, mirroring the vendor’s own path. After every composer install (which restores the vanilla vendor file), the restore script copies your version back over it.

   • ✅ The original vendor path is preserved inside the overlay folder, and a restore step re-applies it.

2. Give it a MOD-NNN identifier and log it so future-you (and the next vendor update) knows the patch exists and how to re-apply it.

   • ✅ The customization has a tracked MOD-NNN entry.

3. Ask: am I adding columns to a vendor table?

Database changes have their own hard rule: never edit a vendor migration. You make every change in your own migration file — and there are two safe homes for new data.

1. A new attribute on a vendor row → an additive _zaj migration. Need a column like whitelabel_domain on users? Write a separate migration {date}_add_{cols}_to_{table}_zaj.php that adds the marked column directly to the vendor table — never touch the vendor’s own migration.

   Schema::table('users', fn (Blueprint $t) =>
     $t->string('whitelabel_domain')->nullable()->comment('ZAJ: <App> v<ver> — whitelabel'));

   • ✅ A new _zaj-suffixed migration adds the column; the ZAJ: comment marks it as yours in the live schema.

2. Genuinely new data → a zajm_ table. A loyalty ledger, event log, anything that isn’t just an attribute of a vendor row goes in a table your ZajModule owns, named zajm_{module}_{noun}, in packages/ZajModules/*/Database/Migrations/.

   • ✅ The new table lives outside database/migrations/ (vendor-only), so a vendor update never sees it.

Two database rules that never bend

Never edit a vendor migration, and never run raw ALTER TABLE by hand. Add columns only through an additive, reversible _zaj migration (nullable columns + a down() that drops them) — the Atlas schema-diff in Vendor Updates catches any clash (the vendor adding the same column) before it lands.

4. Worked examples — route three real changes

Run the three questions against concrete requests to see the rule in action.

The change	Question it answers	Home
Send new signups to an email-marketing service	New functionality (listen to the Registered event)	ZajModule at packages/ZajModules/System/EmailMarketing/Encharge/
The vendor’s dashboard migration scanner misses your module paths, so it wrongly redirects to /update	Editing an existing vendor file with no override point	Vendor customization of app/Http/Controllers/HomeController.php, tracked as a MOD-NNN
Store a per-plan feature limit that the vendor’s plans table doesn’t have	Adding a column to a vendor table	_zaj migration add_feature_limit_to_plans_zaj.php — adds the marked column to plans

Each lands in a home the vendor never touches — which is the entire point.

Checklist

Do not mark this step done until every box below is checked.

• 👤 New vs existing decided — you know whether the change is brand-new functionality (ZajModule) or an edit to a vendor file.
• 👤 Event-driven ruled out first — for any vendor edit, you confirmed no event hook or override could do the job.
• 👤 Database rule applied — columns are added to the vendor table via a marked additive _zaj migration (never by editing a vendor migration); genuinely new data goes in a zajm_ table.
• 👤 Home named — for your specific change, you can state which of the three homes it belongs in and why.

→Next step

Build a ZajModule