# 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 3 — AI generation (built; waiting for a real test with API keys) **Next action:** Add the Anthropic and DeepSeek API keys to `.env`, switch the two providers from `fake` to `claude` and `deepseek`, and test a real generation and a real edit. Then start Step 4 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`: 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: a theme (8 colours, heading font, body font, corner radius) and an ordered list of sections. - Each section has an `id`, a `type`, a `variant` (layout) and `content` (the text). - `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. - 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`. - Three providers exist: `claude`, `deepseek`, and `fake`. The `fake` one needs no key and costs nothing: it returns the built-in sample design. Local `.env` uses `fake` until the real keys are added. - 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 `.env` - [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; not yet run against the real service) - [x] DeepSeek for small edits (built; not yet run against the real service) - [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 - [ ] Real test with API keys: one generation with Claude, one edit with DeepSeek, then tune the prompts if needed ### Step 4 — Commerce - [ ] Products: create, edit, images, price, stock - [ ] Product page and collection page - [ ] Cart - [ ] Checkout with Stripe Malaysia (test mode) - [ ] Orders list for the merchant - [ ] Order confirmation email ### 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` | - Database: MySQL, database `ai_commerce`, settings in `.env`. - Local test login: created by `php artisan db:seed`. Email is in `database/seeders/DatabaseSeeder.php`, password in `database/factories/UserFactory.php`. - AI: local `.env` uses the `fake` provider. To use 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` 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/` | | 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 - Anthropic API key and DeepSeek API key: needed in `.env` for the real test of Step 3 - 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 |