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-18
Current step: Step 9 — Modern store design (part 1 done; next: part 2, announcement bar and trust row)
Next action: Commit part 1 on redesign/part-1-photo-hero (do not merge into main yet). Then create redesign/part-2-announcement-bar from it and build the announcement bar and trust row. Step 7 part 2 still waits for an EasyParcel API key
Status marks: [ ] not started · [~] in progress · [x] done
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 |
| 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) |
| 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 |
| Order notifications and chat button |
Changing from Claude to another AI model (or back) must be a settings change, not a code rewrite.
.env.local: which provider and which model. Example:
AI_GENERATE_PROVIDER=claude, AI_GENERATE_MODEL=claude-sonnet-5-5AI_EDIT_PROVIDER=deepseek, AI_EDIT_MODEL=deepseek-chatplan 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.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, products, cart, checkout and a few more) cannot be used as page ids.#section-id scrolls on the home page, /shop opens the Shop page. The storefront turns these into real addresses./ plus the page id, such as /about. PlanValidator rejects a link to a page that does not exist.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.public storage disk, which needs php artisan storage:link once per machine.PaymentGateway), like the AI layer. Stripe is the only provider for now.PlanSchema.php and types.ts, write one React component, add one line in renderer.tsx.--sf-* CSS variables, so it never mixes with the dashboard theme.AiManager. It reads config/ai.php, which reads .env.local.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.config/ai.php.PlanSchema.php) and the brand description, and answers with a store plan.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.store_generations table, which also drives the progress screen and counts usage.config/plans.php.plan column of the users table.<store name>.<domain>. 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.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.App\Storefront\Storefront is the only place that knows the difference: which store, which design, and what the links are built on.www, admin, login and so on). Such a store gets a number added, for example login-2.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.trial_ends_at 14 days ahead. While that date is in the future the account is on the free trial.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.past_due (a card failed and Stripe is retrying).SubscriptionGateway), like payments and AI.shipping_west, shipping_east, free_shipping_over). Sabah, Sarawak and Labuan use the east fee; every other state uses the west fee.ShippingProvider). FlatRateShipping is the first provider; EasyParcel live rates can replace it in one place.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.60123456789). Only Malaysian numbers are accepted. MalaysianPhone does the cleaning.App\Storefront\StorefrontText; words drawn in the browser live in resources/js/storefront/text.ts.discount_codes table, per store, saved in capital letters. Shoppers may type them in any case.discount_code and discount_total. Deleting or changing a code later never changes old orders.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.12-34). A product with options must be bought as one of its variants.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.is_bundle on. bundle_items lists what is inside: a product (and, for a product with options, one variant) and how many.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.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.discount_name (codes stay in discount_code). Stripe’s page, the thank-you page, the email and the merchant’s order page all show it.create_automatic_discount (“buy 2 sambal, get 15% off until end of January”), with the same confirm step as other chat commands.actions: create_product, update_product (name, price, “was” price, stock, status, per variant for products with options), create_discount, update_discount (on/off, last day, number of uses) and create_bundle. At most 10 per message.App\Commerce\ChatActions checks each action with the same rules as the Products and Discounts forms (discount rules are shared through DiscountCodeRules). A wrong product, choice or code goes back to the AI once to fix, like a bad design answer.store_generations.actions, actions_status) and shown as plain sentences, such as “Change “Moisturiser (100ml)”: price RM 55.00 → RM 52.00”. Nothing changes until the merchant clicks Confirm. Cancel changes nothing.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.image-full (a photo across the whole width, words on top with a dark fade so they stay readable), split (words beside a tall photo) and centered (words only, as before).image field names a photo: upload:12 (a banner photo uploaded in the Design tab, saved in store_images) or product:web-address-name (that product’s main photo). Null means automatic: the store’s newest active product photo. With no photos at all, the hero shows a soft pattern in the store’s colours.store_generations.changed.| 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 |
php is still 8.2)ai_commerce)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 testedstore_id (applies from Step 2 on)fake AI provider)storename.localhost:8000). Shoppers need no loginplans table; prices in sen)Part 1 (done 2026-11-16, no new accounts needed):
wa.me links, no account needed)Part 2 (needs outside accounts):
ShippingProvider)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.
Notes:
Agreed on 2026-11-17 after comparing our stores with 2026 design trends (research page: https://claude.ai/artifact/EngaK7gb3yhe4Jt1JDkPce). Our stores look plain mainly because they show placeholder shapes instead of photos, and because every store has the same structure (centred text on a flat colour, then a grid). Build in this order, biggest visible change first:
Branches (agreed 2026-11-18):
redesign/part-{number}-{short-title}, such as redesign/part-1-photo-hero and redesign/part-2-announcement-bar. (Git does not allow spaces or “:” in branch names, so dashes are used.)main: part 2 from part 1, part 3 from part 2, and so on.main until the merchant decides.Notes:
| 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) |
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 |
.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.ai_commerce, settings in .env.local.php artisan db:seed. Email is in database/seeders/DatabaseSeeder.php, password in database/factories/UserFactory.php..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.composer run dev starts it. Without it, a job waits and is marked failed after 10 minutes.storage/logs/laravel.log, not sent.https://git.mirfalah.my/mirfalah-tech/ai_commerce.git (remote name origin). The .env.local file is never uploaded.| 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 |
| Chat commands | app/Commerce/ChatActions.php, StoreGenerationController::confirm, resources/js/components/stores/design-chat.tsx |
| Automatic discounts | app/Models/AutomaticDiscount.php, app/Commerce/AutomaticDiscountRules.php, Cart::applied, AutomaticDiscountController |
| Hero photos | app/StorePlan/HeroImages.php, HeroImageController, resources/js/storefront/sections/hero.tsx, components/stores/hero-picker.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/ |
.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.Moved into Step 9 — Modern store design on 2026-11-17.
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 |
| 2026-11-17 | Step 8 part 4 on branch feature/chat-commands: chat commands for products, discount codes and bundles, with Confirm and Cancel in the chat. Shared discount rules. Fixed a test that failed by chance (random stock). 233 tests pass; with real DeepSeek, “GLOW15 until end of month + 100ml to RM 52” was proposed, confirmed and saved; a product + bundle request was proposed correctly and cancelled. |
Merge; then automatic discounts, Step 7 part 2 or Step 9 |
| 2026-11-17 | Step 8 part 5 on branch feature/automatic-discounts: automatic discounts (Discounts tab form, best-of-one rule with codes, cart nudge, product page note, order/Stripe/email name, chat command). Step 8 is done. 243 tests pass; real Stripe test payment with “Glow Week” (2 cleansers, −RM 8.40, total RM 83.60) worked, GLOW15 correctly won when typed; real DeepSeek proposed a sunscreen-only sale correctly (cancelled). |
Merge; then Step 7 part 2 or Step 9 |
| 2026-11-17 | Chat commands can write product descriptions from the product name (same branch, feature/automatic-discounts). Real DeepSeek test found the AI guessing bundle contents, so bundle contents are now listed for it; second try was accurate. 244 tests pass. |
Merge; then Step 7 part 2 or Step 9 |
| 2026-11-17 | Researched 2026 store design trends and published a comparison page. Added Step 9 — Modern store design (6 parts) and the category guides decision; “Before launch” is now Step 10. | Step 9 part 1: photos first |
| 2026-11-18 | Step 9 part 1 on branch redesign/part-1-photo-hero: full-width and split photo heroes, hero photo upload and picker in the Design tab, automatic product photo, second photo on hover, letter placeholders, AI told about photos. 251 tests pass; checked in the browser at desktop and phone width with a test banner on Luna Skin. |
Merge, then part 2 |