# AI Commerce — Progress Tracker This file is the single source of truth for the project plan and status. Update it at the end of every work session. **Last updated:** 2026-11-16 **Current step:** Step 8 — Discounts and product options (discount codes, product variants and bundles done; next: chat commands) **Next action:** Merge `feature/bundles` into `main`. Then build chat commands for products, discounts and bundles, with a confirm step. Step 7 part 2 still waits for an EasyParcel API key Status marks: `[ ]` not started · `[~]` in progress · `[x]` done --- ## 1. What we are building An AI store generator for ecommerce only, similar to amboras.com. A customer describes their brand, and the AI builds a complete online store. | Topic | Decision | | ---------------- | ------------------------------------------ | | Customers | First-time founders and existing merchants | | Market | Malaysia first | | Team | Solo, as a business | | Where we develop | Local machine first, no hosting yet | ## 2. Decisions ### Confirmed | Topic | Decision | | ----------------------------- | -------------------------------------------------------------- | | Backend | Laravel 13 on PHP 8.3 / 8.4 | | Frontend | React + TypeScript | | Payments | Stripe Malaysia | | AI for first store generation | Claude Sonnet 5.5 (`claude-sonnet-5-5`) | | Pricing rule | Each plan has a limited number of full regenerations per month | | Template reuse | Later improvement (see section 6) | ### Confirmed on 2026-11-14 (previously proposed) | Topic | Decision | | --------------------- | --------------------------------------------------------------------- | | Laravel + React link | Inertia.js (official Laravel React starter kit) | | Styling | Tailwind + shadcn/ui | | Database | MySQL (already installed), one database, `store_id` on every table | | Background jobs | Laravel queues (database driver first, Redis later) | | Commerce backend | Our own: products, cart, orders, checkout. Not built on Shopify | | How AI builds a store | AI picks and fills pre-built React sections. It never writes raw code | | Store data | Saved as a "store plan"; later edits change small parts of it | | AI for small edits | DeepSeek, called directly from Laravel (not through Hermes) | | AI design | One swappable AI layer, so each task can use a different model | | Shipping | EasyParcel | | Languages | Bahasa Malaysia and English | | WhatsApp | Order notifications and chat button | ### Rule: the AI model must be easy to change Changing from Claude to another AI model (or back) must be a settings change, not a code rewrite. - All AI calls go through one place in the code (the "AI layer"). No other code talks to an AI provider directly. - Each provider (Claude, DeepSeek, others later) is one small "driver" class behind the same interface. - Each task has its own setting in `.env.local`: which provider and which model. Example: - `AI_GENERATE_PROVIDER=claude`, `AI_GENERATE_MODEL=claude-sonnet-5-5` - `AI_EDIT_PROVIDER=deepseek`, `AI_EDIT_MODEL=deepseek-chat` - Prompts and the store plan format are ours and do not depend on any provider. - Every AI result is checked against the store plan format, so a weaker model cannot break a store. - To add a new provider: write one driver class, add its API key, change the setting. ### How the store plan works (added in Step 2) - A store plan is saved in the `plan` column of the `stores` table as JSON. Since Step 4 it is version 2: a theme (8 colours, heading font, body font, corner radius), one header and one footer shared by every page, and a list of pages. The first page is always `home`. - Each page has an `id`, a `title` and an ordered list of sections. Each section has an `id`, a `type`, a `variant` (layout) and `content` (the text). Section ids are unique in the whole plan. - Shop, product, cart and checkout pages are not in the plan. We build them ourselves, the same for every store, in the store's colours and fonts. Their addresses (`shop`, `products`, `cart`, `checkout` and a few more) cannot be used as page ids. - Links in a plan: `#section-id` scrolls on the home page, `/shop` opens the Shop page. The storefront turns these into real addresses. - A link to another page is `/` plus the page id, such as `/about`. `PlanValidator` rejects a link to a page that does not exist. - When a chat edit adds a page, the app adds a menu link to it if the AI forgot (header first, footer if the header is full). When a page is removed, links to it are removed too. - `PlanUpgrader` converts an old version 1 plan to version 2. - `PlanSchema.php` is the one place that says what is allowed. `PlanValidator` checks every plan before saving and removes anything unknown. Links can only point inside the page, inside the site, or to `https`, `mailto` and `tel` addresses. - Products: prices are saved in sen (whole numbers) to avoid rounding errors. Photos are saved on the `public` storage disk, which needs `php artisan storage:link` once per machine. - Cart: only product ids and quantities are saved in the session. Prices and stock are always read fresh, so the cart never shows an old price, and it corrects itself when stock runs low or a product is hidden. - Checkout: the shopper fills in contact details and a Malaysian address, we save an order as "Awaiting payment", then send them to Stripe's own payment page. Card details never touch our server. - An order keeps its own copy of product names and prices, so it never changes when a product is edited or deleted later. Order numbers count up per store from 1001. - An order becomes "Paid" only after we ask Stripe directly and the amount matches. Then stock goes down, the cart is emptied and the email is sent. This happens once, even if both the return page and the webhook report the payment. - Payments go through one interface (`PaymentGateway`), like the AI layer. Stripe is the only provider for now. - Stripe shows whichever payment methods are switched on in the Stripe dashboard for MYR (cards now; FPX and e-wallets can be switched on there, Step 7). - Until a store has real products, its home page shows the example products the AI wrote. - To add a new section type: add it to `PlanSchema.php` and `types.ts`, write one React component, add one line in `renderer.tsx`. - The storefront uses its own colours through `--sf-*` CSS variables, so it never mixes with the dashboard theme. ### How AI generation works (added in Step 3) - All AI calls go through `AiManager`. It reads `config/ai.php`, which reads `.env.local`. - Three providers exist: `claude`, `deepseek`, and `fake`. The `fake` one needs no key and costs nothing: it returns the built-in sample design. Use `fake` for free development work. - The DeepSeek driver speaks a common format that many providers share, so most new providers need only a few lines in `config/ai.php`. - A full design: the AI gets our rules (built from `PlanSchema.php`) and the brand description, and answers with a store plan. - A chat edit: the AI gets the current plan and the request, and answers with only what to change. We apply that to the plan. - Every answer goes through `PlanValidator`. If it fails, the AI gets one chance to correct it. If it fails again, the job fails and the store is not changed. - AI work runs in the background. Each job is one row in the `store_generations` table, which also drives the progress screen and counts usage. - Limits: the first design of a store is free. Later full designs count as regenerations. Failed jobs never count. Limits are in `config/plans.php`. - Until Step 6 (billing), every user is on the free trial. The plan name is stored in the `plan` column of the `users` table. - The AI is told not to invent facts (awards, halal or other certificates, contact details) that the merchant did not give. ### How publishing works (added in Step 5) - A published store opens at `.`. The domain is `localhost` on a development machine and is set with `STOREFRONT_DOMAIN` once the app is hosted. The port and http/https come from the address the app itself is opened at. - The `stores` table has `published_plan` (the copy shoppers see) and `published_at`. `plan` stays the working design. Publishing copies `plan` into `published_plan` after checking it once more. - Products, prices and stock are always live. Only the design waits for "Publish changes". - The same controllers and screens serve the live store and the owner's preview. `App\Storefront\Storefront` is the only place that knows the difference: which store, which design, and what the links are built on. - On a store's address only store pages exist. Everything else, including the dashboard and login, gives "not found". - Taking a store offline keeps the design, products and orders. - Some store names cannot be used as addresses (`www`, `admin`, `login` and so on). Such a store gets a number added, for example `login-2`. ### How billing works (added in Step 6) - Plans live in the `plans` table, not in code, so prices and limits can change without a release. `config/plans.php` holds only the trial length and the trial plan's key. - Every new account gets `trial_ends_at` 14 days ahead. While that date is in the future the account is on the free trial. - A paid plan is one row in `subscriptions`, a copy of what Stripe says. Stripe is the source of truth. The copy is refreshed when the merchant comes back from Stripe, every time the Billing page opens, and by the webhook. - An account's current plan is: an active paid plan, otherwise the free trial while it lasts, otherwise nothing. "Active" includes `past_due` (a card failed and Stripe is retrying). - With no plan: AI, new stores and publishing are refused, and live stores show "not found". Nothing is deleted, and everything returns once a plan is chosen. - The Stripe product and price for each plan are created the first time someone subscribes to it, and saved on the plan. - Switching plans changes the existing subscription; Stripe charges or credits the difference on the next bill. - Subscriptions go through one interface (`SubscriptionGateway`), like payments and AI. ### How shipping and WhatsApp work (added in Step 7) - Shipping fees are stored on the store in sen (`shipping_west`, `shipping_east`, `free_shipping_over`). Sabah, Sarawak and Labuan use the east fee; every other state uses the west fee. - The fee goes through one interface (`ShippingProvider`). `FlatRateShipping` is the first provider; EasyParcel live rates can replace it in one place. - The order saves `shipping_total`, and Stripe must collect subtotal plus shipping before the order counts as paid. - `shipped_at`, `shipping_courier` and `tracking_number` on the order record the delivery. Only paid orders can be shipped. - WhatsApp numbers are saved as digits with country code (`60123456789`). Only Malaysian numbers are accepted. `MalaysianPhone` does the cleaning. - Messages the server shows to shoppers live in `App\Storefront\StorefrontText`; words drawn in the browser live in `resources/js/storefront/text.ts`. ### How discount codes work (added in Step 8) - Codes live in the `discount_codes` table, per store, saved in capital letters. Shoppers may type them in any case. - A code takes money off the **products only**, never off shipping. Percentages are rounded down to the sen. A fixed amount never takes off more than the products cost. - Free shipping is judged on the product price **after** the discount. - The code in a cart is kept in the shopper's session. The cart checks it every time: a code that was switched off, expired or used up is taken out, and the shopper is told. A code that needs a bigger cart stays, with a "spend at least RM X" message, and is worth nothing until then. - If the code stopped working between the cart and paying, checkout stops with a message, so the total never surprises the shopper. - After the discount, the order total must still be at least RM 2.00 (Stripe's minimum). - The order saves `discount_code` and `discount_total`. Deleting or changing a code later never changes old orders. - A code counts as used only when its order is **paid**, once per order. Two shoppers paying at the same moment could both use the last remaining use; this is accepted. - Stripe gets a one-off coupon worth exactly the discount, so its page shows the code and the saving. - Days are Malaysian days: a code runs from the start of its first day to the end of its last day in Malaysian time. ### How product variants work (added in Step 8) - A product's `options` hold up to 2 options with their choices, such as `[{"name": "Size", "values": ["250g", "500g"]}]`. Null means a simple product. - `product_variants` has one row per combination (`option1`, `option2`), each with its own price, "price before discount" and stock, in sen. - For a product with options, the product's own price is the lowest variant price and its stock is all variants together. This keeps lists, cards and the featured section right; they show "From RM X" when variant prices differ. - In the cart each line is named after the product, or "product-variant" (for example `12-34`). A product with options must be bought as one of its variants. - Order lines keep the variant's name (`variant_name`) and include it in the line name, such as "Sambal (500g / Pedas)", so emails, Stripe and order pages all show the choice. Paying lowers the chosen variant's stock. - Editing a product keeps variants whose choices did not change, so carts holding them stay valid. Combinations that disappear are removed. - Limits: 2 options, 20 choices per option, 50 combinations. ### How bundles work (added in Step 8) - A bundle is a product with `is_bundle` on. `bundle_items` lists what is inside: a product (and, for a product with options, one variant) and how many. - A bundle has its own price (and optional "price before discount"), but no stock of its own. Its stock is how many times the items allow, for example 10 sambal ÷ 2 and 3 kerepek ÷ 1 gives 3. `BundleStock::refresh()` saves that number on the bundle whenever stock in the store changes (product saved or deleted, order paid), so lists, cards and the cart read it like any other product. - A bundle cannot hold itself, another bundle, or a product of another store. A product with options must name one of its variants. Up to 10 items, up to 20 of each. - Products inside a bundle are protected: they cannot be deleted, become a bundle, gain or lose options, or lose a choice the bundle holds. The merchant takes them out of the bundle first. - At checkout, a bundle and the same items bought on their own are checked together against the stock. - Each order line for a bundle keeps `bundle_contents` (what was inside at the time). Paying lowers the stock of those items. The merchant's order page shows "Each has: 1 × Cleanser, 1 × Moisturiser (50ml)" for packing. - The product form shows "Bought one by one: RM X" and how many bundles can be sold, to help set the price. The storefront product page shows "What's inside" with links to the items. ### How the featured product section works (fixed in Step 7) - A `featured_product` section may hold `productSlug`: the web-address name of one of the store's active products. Product web-address names never change, even when a product is renamed, so the link stays good. - Linked: the store shows the product's real name, price, "price before discount", photo and sold-out state, and the button opens the product page. The AI's description and bullet points stay. - Not linked and the store has products: the price is hidden, because the AI's price is only an example. - Not linked and the store has no products: the AI's example name and price show, so a new store never looks empty. - The merchant links it with the "Featured product" picker on the Design tab, or by chat. The AI is given the store's product list; a made-up product name is sent back to the AI to fix. - The link is part of the design, so on a live store it shows after "Publish changes". Price and stock changes show straight away. - A linked product that is sold out shows a "Sold out" label, and its button says "View product". ### AI edits must really change something (added 2026-11-16) - In a real test, the edit AI replied "Done" without including the change. The app no longer trusts the reply for this: it compares the design before and after each chat edit and saves the answer in `store_generations.changed`. - When nothing changed, the chat shows "No change was made to your design." under the AI's reply. ### Plan prices and limits (starting numbers, adjust after real usage) | Plan | Price / month | Stores | Full regenerations / month | AI edits / month | | -------------------- | ------------- | ------ | -------------------------- | ---------------- | | Free trial (14 days) | RM0 | 1 | 2 in total | 30 in total | | Starter | RM39 | 1 | 3 | 100 | | Growth | RM99 | 3 | 10 | 500 | | Pro | RM249 | 10 | 30 | 2,000 | --- ## 3. Plan, step by step ### Step 0 — Prepare the local machine - [x] Check installed tools (see section 4) - [x] Install PHP 8.4 (8.4.27, via Homebrew; default `php` is still 8.2) - [x] Create a MySQL database for the project (`ai_commerce`) - [x] Set up git in this folder - [x] Code is in the private repository `https://git.mirfalah.my/mirfalah-tech/ai_commerce.git`. `main` holds Steps 1 to 4 (merged 2026-11-15). Each new step is built on its own branch and merged into `main` when finished and tested ### Step 1 — Project foundation - [x] Create Laravel 13 project with the React + TypeScript starter kit (Laravel 13.42, Inertia 3, React 19) - [x] Confirm the app runs locally - [x] Register, login, logout (from the starter kit, with email verification and two-factor login; passkeys left out) - [x] "Create a store" flow (name, category, language, description) - [x] Dashboard that lists the user's stores - [x] Users only see their own stores (other people's stores give "not found") - [ ] Ongoing rule: every new store-related table gets `store_id` (applies from Step 2 on) ### Step 2 — Store sections and renderer - [x] Define the "store plan" format (colours, fonts, corner radius, sections, text) and a validator that every plan must pass - [x] Build 10 React sections, each with 2 layout variants: header, hero, product grid, featured product, about, testimonials, FAQ, newsletter, contact, footer - [x] Renderer that turns a store plan into a storefront page - [x] Preview a store inside the dashboard (desktop and mobile size, plus open as full page) - [x] One hand-written sample plan to prove the renderer works (the "Apply sample design" button was removed in Step 3; the sample plan is now used by the `fake` AI provider) - [ ] Known gaps, to do later: mobile menu for header links; real images (placeholders for now); newsletter form does not save ### Step 3 — AI generation - [x] Swappable AI layer: one interface, one driver per provider, provider and model chosen per task in the settings file - [x] Test: switch the generation model in settings and confirm it works with no code change (automated test) - [x] Claude Sonnet 5.5 for first store generation (built with Anthropic's official PHP package) - [x] DeepSeek for small edits - [x] Run generation as a background job with a progress screen - [x] Check the AI result is a valid store plan before saving (one automatic correction, then fail and leave the store unchanged) - [x] Edit by chat ("make the banner darker") - [x] Count and limit regenerations and edits per plan - [x] Real test with API keys (2026-11-14): two stores generated with Claude Sonnet 5.5 in 13 to 19 seconds each, about 4,000 tokens in and 2,000 to 2,600 out (roughly US$0.03 per store). Two edits with DeepSeek in 1 to 2 seconds each. All answers passed the checker first time. Prompt tuned once so layouts differ between brands ### Step 4 — Commerce - [x] Store plan format changed to support several pages (version 2): one shared header and footer, plus a list of pages. Existing stores were converted automatically - [x] Products: create, edit, delete, up to 5 photos, price, price before discount, stock, draft or active - [x] Shop page (all products) and product page, built by us, in the store's colours and fonts - [x] The home page product section shows real products once the merchant adds some, with a "View all" button - [x] Cart: add from the product page, change quantity, remove, subtotal, cart count in the header. Kept in the browser session, one cart per store, no account needed - [x] Checkout with Stripe Malaysia (test mode): shopper details and address, then Stripe's hosted payment page. Tested with a real Stripe test payment on 2026-11-15 - [x] Orders list and order page for the merchant ("Orders" tab) - [x] Order confirmation email, in the store's language, sent once when the order is paid - [ ] Known gaps, to do later: (shipping fee and "mark as shipped" were done in Step 7 part 1); unpaid orders stay in the list as "Awaiting payment"; the Stripe webhook needs a public address, so it only starts working after hosting (Step 9) - [x] Content pages by chat ("add an About page", "remove the About page"): the AI creates the page, and the app itself makes sure the menu links to it. Tested with real DeepSeek on 2026-11-15 ### Step 5 — Publishing - [x] Publish a store to its own address (local: `storename.localhost:8000`). Shoppers need no login - [x] "Publish store", "Publish changes" and "Take offline" buttons on the store page, with the live address shown - [x] Shoppers see a saved copy of the design, so design changes stay private until the merchant publishes again - [x] The whole shop works on the live address: home, extra pages, shop, product, cart, checkout, thank-you page - [x] The dashboard and login pages cannot be opened on a store's address - [ ] Custom domains (after hosting is chosen, Step 9) - [ ] Known gaps, to do before launch: pages are drawn in the shopper's browser, so search engines may read them poorly (fix: server-side rendering); no page description or sharing image for search and social media yet; the browser tab shows our app name for a moment while a page loads ### Step 6 — Our own subscription billing - [x] Plans table matching the price table above (`plans` table; prices in sen) - [x] Subscribe, upgrade, downgrade and cancel through Stripe (Billing page). Cancel keeps the plan until the end of the paid month and can be undone - [x] Free trial of 14 days for every new account (existing test accounts got a fresh 14 days) - [x] Enforce plan limits: stores, regenerations and AI edits. When the trial ends with no plan, AI, new stores and publishing are switched off and live stores go offline; nothing is deleted - [x] Tested with a real Stripe test subscription on 2026-11-16: subscribe to Growth, cancel, undo - [ ] Known gaps, to do later: a merchant who downgrades keeps stores above the new limit (they just cannot add more); no invoices page yet (Stripe sends receipts); no email before the trial ends; the subscription webhook needs hosting, like the order webhook ### Step 7 — Malaysia features Part 1 (done 2026-11-16, no new accounts needed): - [x] Store "Settings" tab: WhatsApp number and shipping fees - [x] Flat shipping fees: one for Peninsular Malaysia (default RM 8), one for Sabah, Sarawak and Labuan (default RM 15), optional free shipping above an amount. Shown at checkout as soon as a state is chosen, on Stripe's page as its own line, on the thank-you page and in the email - [x] "Mark as shipped" on the merchant's order page, with courier and tracking number. The shopper gets a "your order is on its way" email once; later corrections do not email again - [x] WhatsApp chat button on every page of the store, "Ask about this order on WhatsApp" on the thank-you page, and "WhatsApp customer" on the merchant's order page (all `wa.me` links, no account needed) - [x] Bahasa Malaysia and English store generation (already working since Step 3; checked again) - [x] Checkout and cart error messages in the store's language - [x] Checked which payment methods the Stripe account has: cards on; FPX and GrabPay supported by Stripe in Malaysia but not switched on yet (switch on in the Stripe dashboard, no code change). DuitNow QR, Touch 'n Go and Boost are not offered by Stripe - [x] Tested with a real Stripe test payment on 2026-11-16: Sabah order, RM 15 shipping, total RM 70; then marked as shipped - [x] Fix: the "featured product" section can now be linked to a real product (picker on the Design tab, or by chat: "feature the green sambal"). Its real name, price, photo and page are shown. Before, it showed the AI's made-up name and price Part 2 (needs outside accounts): - [ ] Switch on FPX and GrabPay in the Stripe dashboard (your action), then test an FPX payment - [ ] EasyParcel live shipping rates and labels (needs an EasyParcel demo account and API key; plugs in behind `ShippingProvider`) - [ ] Automatic WhatsApp order notifications (needs a WhatsApp Business Platform account from Meta, with approved message templates) - [ ] DuitNow QR and Malaysian e-wallets: only through a second payment provider (for example Billplz, ToyyibPay, HitPay or Fiuu). Decide whether it is worth it ### Step 8 — Discounts and product options Agreed on 2026-11-15. Build in this order. It comes after Step 7 because automatic discounts such as free shipping need shipping to exist. - [x] Discount codes (done 2026-11-16): "Discounts" tab for the merchant (code, percent or fixed amount off, optional minimum spend, first and last day, number of uses, on or off); a "Discount code" box in the cart; the order records the code and the amount taken off; Stripe shows the code and the saving. Tested with a real Stripe test payment: RM 42.00 − 20% (RM 8.40) + RM 8.00 shipping = RM 41.60 - [x] Product variants (done 2026-11-16): up to 2 options per product (such as Size and Flavour), with a price, "price before discount" and stock for every combination. Shoppers pick with buttons on the product page; sold-out choices are crossed out. Each choice is its own cart line, order line and stock count. Tested with a real Stripe test payment - [x] Bundles with linked stock (done 2026-11-16): a product made of other products, with one bundle price. The product page shows what is included and the saving ("price before discount" crossed out). Selling a bundle lowers the stock of each item in it, and a bundle is sold out when any item is sold out. Tested with a real Stripe test payment - [ ] Chat commands for products, discounts and bundles ("create a bundle of the cleanser and moisturiser for RM 85", "make a 10% code RAYA10"). The AI turns the sentence into an action, the app shows a confirmation, and nothing changes until the merchant confirms - [ ] Later: automatic discounts ("buy 2, get 10% off", "free shipping over RM 100") Notes: - A sale price on one product already works today (the "price before discount" field). - Every feature gets a normal form first. Chat commands are a shortcut on top of the forms. - The confirm step is required for chat commands because these actions involve money. ### Step 9 — Before launch - [ ] Choose hosting and deploy - [ ] Privacy policy and terms of service (name the AI providers) - [ ] Backup AI provider in case one is down - [ ] Spending caps on every AI account --- ## 4. Local machine (checked 2026-11-14) | Tool | Status | | ---------- | ------------------------------------------------------------------------------------------------------------------- | | PHP | 8.4.27 at `/opt/homebrew/opt/php@8.4/bin/php` (used by this project). Default `php` is 8.2.30; 8.5.5 also installed | | Composer | 2.9.7 | | Node / npm | 24.14.1 / 11.11.0 | | MySQL | 9.6.0 | | PostgreSQL | Not installed (not needed, using MySQL) | | Redis | Not installed (not needed yet) | ## 4a. How to run the app locally This project needs PHP 8.4, which is not the default `php` on this machine. In each new terminal, run this first: ```bash export PATH="/opt/homebrew/opt/php@8.4/bin:$PATH" ``` Then, from the project folder: | Task | Command | | ----------------------------------- | ------------------------------------------ | | Start the app (server, queue, Vite) | `composer run dev` | | Open the app | http://localhost:8000 | | Run all tests | `php artisan test` | | Check PHP style and types | `composer lint` and `composer types:check` | | Check frontend | `npm run check` and `npm run types:check` | | Rebuild frontend for tests | `npm run build` | - Settings files: `.env` is uploaded to the repository and holds only basic, non-secret settings (secrets and all AI settings are blank). `.env.local` is never uploaded and holds everything needed to run, including keys. When `.env.local` exists the app reads it instead of `.env`, so it must be complete. This is set up in `bootstrap/app.php`. - Database: MySQL, database `ai_commerce`, settings in `.env.local`. - Local test login: created by `php artisan db:seed`. Email is in `database/seeders/DatabaseSeeder.php`, password in `database/factories/UserFactory.php`. - AI: `.env.local` now uses the real providers (`claude` and `deepseek`), so every generation and edit costs a little money. To work for free, set both providers to `fake`. For real AI, set `AI_GENERATE_PROVIDER=claude` and `AI_EDIT_PROVIDER=deepseek`, and fill in `ANTHROPIC_API_KEY` and `DEEPSEEK_API_KEY`. - AI jobs need the background worker. `composer run dev` starts it. Without it, a job waits and is marked failed after 10 minutes. - Emails (such as verification links) are written to `storage/logs/laravel.log`, not sent. - Code repository: `https://git.mirfalah.my/mirfalah-tech/ai_commerce.git` (remote name `origin`). The `.env.local` file is never uploaded. ## 4b. Where things are in the code | Thing | Location | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Store model | `app/Models/Store.php` | | Store screens logic | `app/Http/Controllers/StoreController.php` | | Store categories, languages, statuses | `app/Enums/` | | Store form rules | `app/Http/Requests/Stores/CreateStoreRequest.php` | | Screens | `resources/js/pages/dashboard.tsx`, `resources/js/pages/stores/` | | Store tests | `tests/Feature/Stores/` | | Store plan format (the rules) | `app/StorePlan/PlanSchema.php` | | Store plan checker | `app/StorePlan/PlanValidator.php` | | Sample plan | `app/StorePlan/SamplePlan.php` | | Preview logic | `app/Http/Controllers/StoreDesignController.php` | | AI settings | `config/ai.php` (providers, models per task) | | AI layer and providers | `app/Ai/`, `app/Ai/Drivers/` | | AI prompts, generation and chat edits | `app/StorePlan/Ai/` | | Start an AI job (buttons) | `app/Http/Controllers/StoreGenerationController.php` | | Background AI job | `app/Jobs/RunStoreGeneration.php` | | Plan limits and usage counting | `config/plans.php`, `app/Billing/UsageLimits.php` | | Progress screen and chat box | `resources/js/components/stores/` | | Product model and photos | `app/Models/Product.php`, `app/Models/ProductImage.php` | | Product screens logic | `app/Http/Controllers/ProductController.php` | | Product screens | `resources/js/pages/stores/products/` | | Storefront Shop and product pages | `resources/js/storefront/pages/` | | Checkout and order logic | `app/Commerce/Checkout.php`, `app/Http/Controllers/CheckoutController.php` | | Payment providers | `app/Commerce/Payments/` (interface and Stripe) | | Stripe webhook | `app/Http/Controllers/StripeWebhookController.php` (address: `/stripe/webhook`) | | Orders for the merchant | `app/Http/Controllers/OrderController.php`, `resources/js/pages/stores/orders/` | | Order email | `app/Mail/OrderConfirmation.php`, `resources/views/mail/orders/` | | Live store or preview (the difference) | `app/Storefront/Storefront.php` | | Live store addresses | top of `routes/web.php`, `config/storefront.php` | | Publish and take offline | `app/Http/Controllers/StorePublishController.php` | | Plans, trial and limits | `app/Models/Plan.php`, `app/Models/User.php` (`currentPlan`), `app/Billing/UsageLimits.php` | | Subscriptions with Stripe | `app/Billing/` (`Billing`, `SubscriptionGateway`, `StripeSubscriptionGateway`) | | Billing page | `app/Http/Controllers/BillingController.php`, `resources/js/pages/billing/` | | Shipping fees | `app/Commerce/Shipping/`, store settings in `app/Http/Controllers/StoreSettingsController.php` | | Store settings page | `resources/js/pages/stores/settings.tsx` | | Mark as shipped and its email | `OrderController::ship`, `app/Mail/OrderShipped.php` | | WhatsApp links and phone cleaning | `app/Support/MalaysianPhone.php`, `resources/js/storefront/whatsapp.tsx` | | Shopper messages in English and Malay | `app/Storefront/StorefrontText.php`, `resources/js/storefront/text.ts` | | Discount codes | `app/Models/DiscountCode.php`, `app/Http/Controllers/DiscountCodeController.php`, `resources/js/pages/stores/discounts/` | | Discount in the cart and checkout | `Cart::applyCode` and `Cart::discount`, `Checkout::placeOrder` | | Product variants | `app/Models/ProductVariant.php`, `SaveProductRequest`, `ProductController::syncVariants`, `resources/js/components/stores/variant-editor.tsx` | | Cart logic | `app/Commerce/Cart.php`, `app/Http/Controllers/CartController.php` | | Bundles | `app/Models/BundleItem.php`, `app/Commerce/BundleStock.php`, `resources/js/components/stores/bundle-editor.tsx` | | Storefront words (English, Malay) | `resources/js/storefront/text.ts` | | Store plan format (frontend types) | `resources/js/storefront/types.ts` | | Storefront renderer and sections | `resources/js/storefront/renderer.tsx`, `resources/js/storefront/sections/` | ## 5. Open questions - **Who receives the money?** Today every payment goes to our own Stripe account (the keys in `.env.local`). Before real merchants sell, each merchant must be paid into their own account. The usual way is Stripe Connect. Decide before launch; it changes the checkout a little and adds an onboarding step for merchants. - **DuitNow QR and e-wallets:** Stripe does not offer them. Adding them means a second payment provider. Decide later, based on what merchants ask for. - Hosting provider (decide at Step 9) ## 6. Later improvements ### Improvement: more design styles (agreed 2026-11-16) Today the AI can choose colours, 2 fonts from 8, corner roundness, which sections, their order, 2 layouts per section, and all text. So a "futuristic" request changes the mood (dark colours, neon accents, a modern font) but every store still uses the same shapes. This improvement lets stores look much more different from each other. Each option is built once by us, added to `PlanSchema.php`, and then the AI can choose it for any store; the safety checker still checks every design. Build in this order: - [ ] Style options in the theme, chosen by the AI or by chat: - effects: none, soft shadows, glow, glass cards - backgrounds: plain, gradient, subtle pattern - buttons: solid, outline, pill - spacing: compact or airy - motion: none, or a gentle fade-in on scroll (always off for visitors who ask their device for less motion) - [ ] More fonts, for example futuristic, handwritten and elegant ones - [ ] More layouts per section: 3 to 4 instead of 2 - [ ] More section types, for example image gallery, video, promo banner, countdown Notes: - Old designs must keep working: every new option has a default that looks like today's stores. - The list of refused chat requests (saved for every AI edit) shows which styles merchants ask for most; build those first. ### Other ideas - **Template library:** save the design skeleton of good generated stores (colours, fonts, section order, style labels, never customer content). Match new customers to a skeleton and let the cheap model personalise it, so the expensive model is skipped. Start the library by generating 30–50 designs ourselves. - Show three matched designs for the customer to choose from. - Import products from Shopee, TikTok Shop, Shopify. - LHDN e-invoicing. - AI product photography, email flows, SEO tools. --- ## 7. Session log Add one line per work session: date, what was done, what is next. | Date | Done | Next | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | 2026-11-14 | Planning. Chose stack, market, payments, AI models, plan prices. Checked local tools. Created this file. All proposed decisions confirmed. Added the rule that the AI model must be easy to change. | Install PHP 8.4, create the Laravel project (Step 0 and Step 1) | | 2026-11-14 | Installed PHP 8.4. Created the Laravel 13 + React project, MySQL database and git repo. Built create-a-store flow and dashboard. 51 tests pass; login and store creation checked in the browser. Step 0 and Step 1 done. | Step 2: store plan format, sections, renderer | | 2026-11-14 | Step 2 done on branch `feature/store-sections-renderer`: store plan format and validator, 10 sections with 2 variants each, renderer, dashboard preview, sample design. 69 tests pass; storefront checked in the browser on desktop and mobile. | Step 3: swappable AI layer and store generation | | 2026-11-14 | First commit made and pushed to the private repository on git.mirfalah.my (branch `feature/store-sections-renderer`). | Step 3: swappable AI layer and store generation | | 2026-11-14 | Step 3 built on branch `feature/ai-generation`: swappable AI layer (Claude, DeepSeek, fake), full store generation, chat edits, background job with progress screen, plan limits. 92 tests pass; whole flow checked in the browser with the fake provider. Not yet run against real Claude or DeepSeek. | Add API keys, run the real test, then Step 4 | | 2026-11-14 | Split settings into `.env` (uploaded, no secrets, AI settings blank) and `.env.local` (private, complete). Removed `.env.example`. | Real AI test, then Step 4 | | 2026-11-14 | Real AI test passed: Claude Sonnet 5.5 generated two stores, DeepSeek made two chat edits. Tuned the prompt for more varied layouts. Step 3 done. | Merge into `main`, then Step 4: products | | 2026-11-14 | Step 4 part 1 on branch `feature/commerce`: store plan version 2 with pages, products with photos, Shop page, product page, real products on the home page. 108 tests pass; checked in the browser; real Claude and DeepSeek re-tested with the new format. | Step 4 part 2: cart, Stripe checkout, orders, email | | 2026-11-14 | Cart built on branch `feature/commerce`: add to cart, quantity, remove, subtotal, header count, stock limits. 118 tests pass; checked in the browser. | Stripe checkout (needs test keys), orders, email | | 2026-11-15 | Step 4 finished on branch `feature/commerce`: checkout with Stripe (test mode), orders for the merchant, order confirmation email. 133 tests pass. A real Stripe test payment worked end to end: order paid, stock lowered, email written to the log. | Merge into `main`, then Step 5: publishing | | 2026-11-15 | Merged Steps 3 and 4 into `main` and pushed. | Step 5: publishing | | 2026-11-15 | Content pages by chat on branch `feature/content-pages`: add, rename and remove pages, each page at its own address, menu links guaranteed by the app. 139 tests pass; tested with real DeepSeek and in the browser. Step 4 is now complete except the known gaps. | Step 5: publishing | | 2026-11-15 | Planning only. Added Step 8 (discount codes, product variants, bundles with linked stock, chat commands with a confirm step), placed after Malaysia features. "Before launch" is now Step 9. Cart items redesigned as cards. | Step 5: publishing | | 2026-11-15 | Step 5 on branch `feature/publishing`: publish and take offline, live stores on their own address, design changes private until published again, dashboard blocked on store addresses. 150 tests pass; Luna Skin published and checked in the browser at `luna-skin.localhost:8000`. | Step 6: subscription billing | | 2026-11-16 | Step 6 on branch `feature/billing`: plans table, 14-day trial, Stripe subscriptions (subscribe, switch, cancel, undo), Billing page, limits enforced, live stores offline when there is no plan. 164 tests pass; real Stripe test subscription to Growth, cancel and undo all worked. Switched the session model from Fable 5.2 to Opus 5.5. | Merge into `main`, then Step 7 | | 2026-11-16 | Step 7 part 1 on branch `feature/malaysia-shipping`: store settings, flat shipping fees (west, east, free over), mark as shipped with tracking and email, WhatsApp buttons, Malay checkout messages, Malaysian phone check. Fixed live-store menu links on pages other than home (bug from Step 5). 178 tests pass; real Stripe test payment with shipping to Sabah worked. | Merge, then Step 7 part 2 or Step 8 | | 2026-11-16 | Featured product fix on branch `feature/featured-product-link` (built on `feature/malaysia-shipping`): the section links to a real product (Design tab picker or chat), shows its real name, price, photo and page, and hides the made-up price otherwise. Added a check that marks chat edits that changed nothing. 191 tests pass; checked in the browser and with real DeepSeek. | Merge both branches, then Step 7 part 2 or Step 8 | | 2026-11-16 | Planning only. Added "more design styles" to later improvements: style options (effects, backgrounds, buttons, spacing, motion), more fonts, more layouts per section, more section types. | Merge branches, then Step 7 part 2 or Step 8 | | 2026-11-16 | Step 8 part 1 on branch `feature/discount-codes`: discount codes (merchant Discounts tab, cart code box, order record, Stripe coupon, use counted when paid). 207 tests pass; real Stripe test payment with a 20% code worked. | Merge, then product variants | | 2026-11-16 | Step 8 part 2 on branch `feature/product-variants` (built on `feature/discount-codes`): product options and variants, option buttons on the product page, variant cart lines, orders and stock. 217 tests pass; real Stripe test payment for a 100ml variant with a discount code worked. | Merge both branches, then bundles | | 2026-11-16 | Step 8 part 3 on branch `feature/bundles`: bundles with linked stock (bundle editor in the product form, "What's inside" on the product page, shared stock check at checkout, order shows what to pack). 223 tests pass; real Stripe test payment for "Glow Starter Set" (cleanser + 50ml moisturiser, RM 69 + RM 8 shipping) lowered both items' stock. | Merge, then chat commands |