# 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 4 — Commerce (part 1 done: pages format, products, Shop page and product page) **Next action:** Step 4 part 2: cart, then checkout with Stripe Malaysia in test mode (needs Stripe test keys in `.env.local`), orders list, order confirmation email 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. - `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. - 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 - [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] First commit, pushed to the private repository `https://git.mirfalah.my/mirfalah-tech/ai_commerce.git`. Branches `main` and `feature/store-sections-renderer` both hold Steps 1 and 2 ### 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 - [ ] Cart - [ ] Checkout with Stripe Malaysia (test mode) - [ ] Orders list for the merchant - [ ] Order confirmation email - [ ] Later in this step or right after: let the merchant add content pages by chat ("add an About page"). The format already supports it ### 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: ```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/` | | 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 - Stripe test keys (publishable and secret) for Step 4 part 2 - 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 |