AI store generator for ecommerce, Malaysia first. Laravel 13 + React + TypeScript.
Вы не можете выбрать более 25 тем Темы должны начинаться с буквы или цифры, могут содержать дефисы(-) и должны содержать не более 35 символов.

PROGRESS.md 27KB

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-14 Current step: Step 5 — Publishing (Step 4 Commerce is done and tested with a real Stripe test payment) Next action: Start Step 5 on a new branch: publish a store so real shoppers can open it (local: storename.localhost)

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.

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

  • Check installed tools (see section 4)
  • Install PHP 8.4 (8.4.27, via Homebrew; default php is still 8.2)
  • Create a MySQL database for the project (ai_commerce)
  • Set up git in this folder
  • 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

  • Create Laravel 13 project with the React + TypeScript starter kit (Laravel 13.42, Inertia 3, React 19)
  • Confirm the app runs locally
  • Register, login, logout (from the starter kit, with email verification and two-factor login; passkeys left out)
  • “Create a store” flow (name, category, language, description)
  • Dashboard that lists the user’s stores
  • 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

  • Define the “store plan” format (colours, fonts, corner radius, sections, text) and a validator that every plan must pass
  • Build 10 React sections, each with 2 layout variants: header, hero, product grid, featured product, about, testimonials, FAQ, newsletter, contact, footer
  • Renderer that turns a store plan into a storefront page
  • Preview a store inside the dashboard (desktop and mobile size, plus open as full page)
  • 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

  • Swappable AI layer: one interface, one driver per provider, provider and model chosen per task in the settings file
  • Test: switch the generation model in settings and confirm it works with no code change (automated test)
  • Claude Sonnet 5.5 for first store generation (built with Anthropic’s official PHP package)
  • DeepSeek for small edits
  • Run generation as a background job with a progress screen
  • Check the AI result is a valid store plan before saving (one automatic correction, then fail and leave the store unchanged)
  • Edit by chat (“make the banner darker”)
  • Count and limit regenerations and edits per plan
  • 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

  • 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
  • Products: create, edit, delete, up to 5 photos, price, price before discount, stock, draft or active
  • Shop page (all products) and product page, built by us, in the store’s colours and fonts
  • The home page product section shows real products once the merchant adds some, with a “View all” button
  • 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
  • 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
  • Orders list and order page for the merchant (“Orders” tab)
  • Order confirmation email, in the store’s language, sent once when the order is paid
  • Known gaps, to do later: shipping fee is RM 0 until EasyParcel (Step 7); the merchant cannot mark an order as shipped yet; unpaid orders stay in the list as “Awaiting payment”; the Stripe webhook needs a public address, so it only starts working after hosting (Step 8)
  • 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

  • Publish a store to a subdomain (local: storename.localhost)
  • Custom domains (after hosting is chosen)

Step 6 — Our own subscription billing

  • Plans table matching the price table above
  • Subscribe, upgrade, cancel through Stripe
  • Free trial of 14 days
  • Enforce plan limits (stores, regenerations, edits)

Step 7 — Malaysia features

  • FPX, DuitNow QR and e-wallets at checkout
  • EasyParcel shipping rates and labels
  • Bahasa Malaysia and English store generation
  • WhatsApp order notifications and chat button

Step 8 — 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:

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/
Cart logic app/Commerce/Cart.php, app/Http/Controllers/CartController.php
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.
  • Hosting provider (decide at Step 8)

6. Later improvements

  • 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