Install and enable

AI Investments is installed from the Extension Manager like every other add-on: activate the licence, install the release, finish it with pnpm updator, switch it on. There is no archive to unpack by hand and no migration to run — the four tables are created by the schema step of pnpm updator, the same sync that creates the core schema. After that you confirm the scheduled task exists, hand out the permissions and decide whether verification is required.

Do core install first. This addon assumes a working platform with wallets, a running cron process and a Super Admin.

Turn the extension on

Three things happen before the switch does anything, in this order: the licence is activated, the release is installed and applied, and only then is the product switched on.

The admin section is additionally wrapped in a licence gate keyed to the addon's internal name, ai_investment. The header and footer render regardless, but the content of every /admin/ai/investment page is held back until the licence check for that name resolves — which is why the licence is activated before anything else.

Confirm the scheduled task

Everything automatic in this product is one cron entry.

The task is registered as processAiInvestments under the ai_investment category, with a period of one hour. Its title on screen is Process AI Investments, described as "Processes active AI investments." It scans every investment at ACTIVE, settles the ones whose term has expired, and leaves the rest alone.

Go to /admin/system/cron and confirm Process AI Investments is listed. It runs on the dedicated cron process (port 4001), not on the API process.

The registry follows the Enabled switch and re-syncs periodically, so switching the extension on schedules the job without a backend restart — and switching it off deregisters the job the same way.

The task is safe to run repeatedly. Every payout is written through the wallet service with an idempotency key derived from the investment id and its outcome, the investment row is locked for update inside the settlement transaction, and an already-recorded payout is treated as proof the money was paid rather than as an error to retry.

Make sure a Super Admin exists

A LOSS settlement is revenue: the part of the principal the user does not get back is credited to the wallet of the oldest user holding the Super Admin role and recorded as platform profit.

If there is no Super Admin role, or the role exists with no users, the fee collector logs [CRITICAL] Dropped platform fee — no Super Admin configured and returns nothing. The settlement itself still completes — the user is paid the correct amount — but the revenue leg is gone and there is no retry.

One more consequence worth knowing: when the investor is the Super Admin, the revenue leg is skipped entirely rather than credited back to themselves. Testing LOSS plans from the Super Admin account will show no platform revenue at all. That is correct behaviour, not a bug.

WIN settlements are unaffected by any of this — they are recorded as a platform loss and need no wallet credit.

Grant the permissions

Fifteen keys control the addon, in three families of five. Assign them at /admin/crm/role.

access.ai.investment.plan and access.ai.investment.duration gate the admin pages in the frontend; the endpoints behind them check the view.* key. See Permissions for how a key maps to an admin path.

Set the KYC gate

One feature gate applies, enforced server-side:

Nothing else in the addon is gated — browsing plans, reading your own investments and cancelling are all ungated.

To make the gate real you need two platform toggles, both under Admin → Settings → Features, Verification: KYC Verification on, and Enforce KYC Feature Access on. The second is off by default, so enabling verification alone changes nothing. Then tick AI Investments on each verification level that should be allowed to invest, in the level builder under Admin → CRM → KYC.

The purchase panel reads the same gate client-side and replaces the form with an explanation of what is required, so a blocked user sees why rather than a failing submit.

Affiliate rewards

Two referral conditions are seeded for this addon. They only do anything if the mlm extension is enabled and the MLM system is configured.

• AI_INVESTMENT — AI Managed Portfolio Bonus. Fires when a referred user opens an investment, calculated on the invested amount. Seeded at 2% with a minimum of 25, and enabled.
• AI_INVESTMENT_PROFIT — AI Investment Profit Share. Seeded at 1% with a minimum of 5, and disabled. Nothing in this addon fires it: settlement deliberately does not process rewards, to avoid paying the referrer twice for the same investment. Enabling it in the affiliate conditions screen will not make it pay out.

The reward is processed after the funding transaction commits and is best-effort — a failure there is logged and never rolls back the investment.

Notification templates

Three templates are seeded and can be edited at /admin/system/notification/template:

AiInvestmentCanceled is seeded and the email helper accepts it, but no route in the addon sends it. A user who cancels an investment gets their refund and no message. Neither the admin status action nor the admin delete sends anything either.

An in-app notification is created on creation and on completion, linking to /ai/investment/{id}. That path does not exist as a page in this build, so the notification's action button lands on a not-found screen. The notification text itself is still the useful part.

Setting MAIL_DISABLED=true in .env stops the platform attempting any outbound delivery, which is worth doing while you exercise these flows — settlement emits one completion email per investment.

Verify the install

Work through this on a staging install before you publish a plan:

Then read Creating plans — two fields on the plan form decide what every investor is paid, three more are shown to users but never enter any calculation, and one of those three is a figure you have to keep accurate by hand.