# AI Commerce An AI store generator for ecommerce. A customer describes their brand, and the AI builds a complete online store for them. - **Customers:** first-time founders and existing merchants - **Market:** Malaysia first - **Status:** in development, running on a local machine only (not hosted yet) > The full plan, all decisions and the current step are in [PROGRESS.md](PROGRESS.md). Read that file first when you continue work. ## Current status | Step | What | Status | | ---- | ------------------------------------------------------- | -------------------------------------------------------------- | | 0 | Prepare the local machine | Done | | 1 | Project foundation: login, create a store, dashboard | Done | | 2 | Store sections, renderer and preview | Done | | 3 | AI generation (Claude Sonnet 5.5, DeepSeek for edits) | Done | | 4 | Commerce: products, cart, checkout with Stripe Malaysia | Done | | 5 | Publishing: subdomains, then custom domains | Done for local use; custom domains wait for hosting | | 6 | Our own subscription billing | Done | | 7 | Malaysia features: FPX, DuitNow, EasyParcel, WhatsApp | Part 1 done (shipping fees, WhatsApp); EasyParcel and FPX next | | 8 | Discounts and product options: codes, variants, bundles | Done | | 9 | Modern store design: photos, styles, category guides | In progress: parts 1–2 done; part 3 next | | 10 | Before launch: hosting, legal pages, backups | Not started | ## What works today - Register, log in, log out, email verification and two-factor login - Create a store (name, category, language, description) - Dashboard that lists your own stores. Other people's stores show "not found" - A saved design for each store, called a **store plan** - 10 storefront sections, each with 2 layouts: header, hero, product grid, featured product, about, testimonials, FAQ, newsletter, contact, footer - A live preview of the storefront inside the dashboard, at desktop and mobile size - "Generate my store": the AI designs the whole store in the background, with a progress screen - Change the design by chat, for example "make the main colour dark green" - Hero banner with a big photo (full width, or beside the words): upload a banner photo or pick a product photo in the Design tab. With no choice, the newest product photo is used - Product cards show a second photo on hover - Announcement bar above the header: free shipping and running automatic discounts appear by themselves, plus up to 3 of the merchant's own lines (Settings tab) - Trust row under the hero: shipping, secure payment and WhatsApp, always taken from the store's real settings - Change the store by chat, for example "make a 10% code RAYA10 until the end of the month" or "set the 100ml moisturiser to RM 52", or "write descriptions for my products". The AI shows what it will do, and nothing changes until you press Confirm - Add or remove whole pages by chat, for example "add an About page". The menu link is added automatically - "Regenerate" for a completely new design, limited by the plan - Usage counting and limits for regenerations and AI edits - A `fake` AI provider that needs no API key, for development and tests - Products: add, edit, delete, up to 5 photos, price, stock, draft or active - Product options such as Size and Flavour, each choice with its own price and stock - Bundles: several products sold together at one price, with stock taken from the products inside - A Shop page with all products and a page for each product, in the store's design - The home page shows the merchant's real products, with a "View all" button - Cart: add products, change quantities, remove items, see the subtotal. No account needed - Checkout with Stripe (test mode): shopper details, Stripe's hosted payment page, thank-you page - Orders tab for the merchant, and an order confirmation email to the shopper - Publishing: a store goes live at its own address (`storename.localhost:8000` on a local machine), with no login for shoppers - Design changes stay private until the merchant clicks "Publish changes" - Shipping fees for Peninsular and East Malaysia, with optional free shipping, and "mark as shipped" with a tracking number - WhatsApp chat button on the store, and WhatsApp links on order pages - Discount codes: percent or fixed amount off, with optional minimum spend, dates and number of uses - Automatic discounts with no code, such as "buy 2, get 10% off", on all or chosen products. Only one discount applies per order: the shopper gets whichever saves more - Billing: 14-day free trial, then Starter, Growth or Pro through Stripe. Merchants can switch or cancel on the Billing page, and plan limits are enforced Known gaps: no phone menu for header links yet, images are placeholders, and the newsletter form does not save sign-ups. ## Tech stack | Part | Choice | | --------------- | ------------------------------------------------------------- | | Backend | Laravel 13 on PHP 8.4 (8.3 also supported) | | Frontend | React 19 + TypeScript, linked to Laravel with Inertia 3 | | Styling | Tailwind CSS v4 + shadcn/ui | | Login | Laravel Fortify | | Database | MySQL (tests use an in-memory SQLite database) | | Background jobs | Laravel queues, database driver | | Payments | Stripe Malaysia (Step 4) | | AI | Claude Sonnet 5.5 for generation, DeepSeek for edits (Step 3) | ## Set up on a new machine You need: PHP 8.3 or 8.4, Composer, Node 24 + npm, and MySQL. 1. Get the code: ```bash git clone https://git.mirfalah.my/mirfalah-tech/ai_commerce.git ``` 2. Create an empty MySQL database named `ai_commerce`. 3. Inside the project folder, create your private settings file from the shared one: ```bash cp .env .env.local ``` 4. Open `.env.local` and fill in the blanks. At least the database user and password, and the AI lines: ``` DB_USERNAME=your_mysql_user DB_PASSWORD=your_mysql_password AI_GENERATE_PROVIDER=fake AI_GENERATE_MODEL=claude-sonnet-5-5 AI_EDIT_PROVIDER=fake AI_EDIT_MODEL=deepseek-chat ANTHROPIC_API_KEY= DEEPSEEK_API_KEY= ``` Use `fake` to work without API keys. Use `claude` and `deepseek`, with the two keys filled in, for real AI. The app key (`APP_KEY`) is created for you in the next step. 5. Install everything, create the tables and build the frontend: ```bash composer run setup ``` 6. Make uploaded product photos visible to the browser (once per machine; `composer run setup` already does this): ```bash php artisan storage:link ``` 7. Optional: create a local test user: ```bash php artisan db:seed ``` The email is in `database/seeders/DatabaseSeeder.php` and the password is in `database/factories/UserFactory.php`. ### The two settings files | File | Uploaded to the repository? | What it holds | | ------------ | --------------------------- | ----------------------------------------------------------------------- | | `.env` | Yes | Basic, non-secret settings. Secrets and all AI settings are blank | | `.env.local` | No, never | Everything needed to run, including the app key, passwords and API keys | When `.env.local` exists, the app reads it **instead of** `.env` (it does not combine the two). So `.env.local` must hold every setting. Never put a real key or password in `.env`. ## Run the app If your default `php` is not 8.3 or 8.4, point the terminal at the right one first. On the main development machine: ```bash export PATH="/opt/homebrew/opt/php@8.4/bin:$PATH" ``` Then start the app (web server, queue worker and frontend together): ```bash composer run dev ``` Open http://localhost:8000. Emails, such as verification links, are not sent. They are written to `storage/logs/laravel.log`. ## Tests and code checks | Task | Command | | ----------------------------------------------------------------- | ---------------------------------------------- | | Run all tests | `php artisan test` | | Rebuild the frontend (needed before tests after changing screens) | `npm run build` | | Fix PHP code style | `composer lint` | | Check PHP types | `vendor/bin/phpstan analyse --memory-limit=1G` | | Check frontend style | `npm run check` | | Check frontend types | `npm run types:check` | ## How a store design works The AI never writes raw code. It picks from sections we have already built and fills in the text. The result is saved as a **store plan**. - A store plan is JSON saved in the `plan` column of the `stores` table. - It has a **theme** (8 colours, a heading font, a body font, corner roundness), one **header** and one **footer** shared by every page, and a list of **pages**. The first page is always `home`. - Each page is an ordered list of **sections**. Each section has an `id`, a `type`, a `variant` (the layout) and `content` (the text). - The Shop, product, cart and checkout pages are not part of the plan. They are built by us, the same for every store, and use the store's colours and fonts. - `app/StorePlan/PlanSchema.php` is the one place that says what is allowed. - `app/StorePlan/PlanValidator.php` checks every plan before it is saved and removes anything unknown. Links can only point inside the page, inside the site, or to `https`, `mailto` and `tel` addresses. This protects stores from a bad AI result. - The storefront uses its own colours (CSS variables starting with `--sf-`), so it never mixes with the dashboard colours. To add a new section type: add it to `PlanSchema.php` and `resources/js/storefront/types.ts`, write one React component, and add one line in `resources/js/storefront/renderer.tsx`. ## AI: easy to change the model Changing from Claude to another AI model is a settings change, not a code rewrite: - All AI calls go through one place in the code, the "AI layer". - Each provider (Claude, DeepSeek, others later) is one small driver class. - Each task picks its provider and model in `.env.local`: ``` AI_GENERATE_PROVIDER=claude AI_GENERATE_MODEL=claude-sonnet-5-5 AI_EDIT_PROVIDER=deepseek AI_EDIT_MODEL=deepseek-chat ``` - Every AI result is checked by `PlanValidator`, so a weaker model cannot break a store. A rejected answer gets one automatic correction; after that the job fails and the store is left unchanged. - The `fake` provider needs no key and returns a built-in sample design. Use it to work on the app without spending money: ``` AI_GENERATE_PROVIDER=fake AI_EDIT_PROVIDER=fake ``` - API keys go in `.env.local` as `ANTHROPIC_API_KEY` and `DEEPSEEK_API_KEY`. Never in `.env`. - AI work runs in the background, so the worker must be running. `composer run dev` starts it. - Settings are in `config/ai.php`. Plan limits are in `config/plans.php`. ## Shipping and WhatsApp - Each store's **Settings** tab holds its WhatsApp number and shipping fees: one fee for Peninsular Malaysia, one for Sabah, Sarawak and Labuan, and an optional free-shipping amount. - The fee is added at checkout and sent to Stripe as its own line. - On an order's page the merchant chooses the courier and tracking number and clicks "Mark as shipped". The shopper gets an email. - WhatsApp buttons are plain `wa.me` links and need no WhatsApp account. Automatic WhatsApp messages need a WhatsApp Business account (Step 7 part 2). - FPX and GrabPay are switched on in the Stripe dashboard, not in this app. Stripe does not offer DuitNow QR. ## Billing - Every new account starts a 14-day free trial. - Plans and their limits are in the `plans` database table. Prices are in sen. - Merchants subscribe on the Billing page through Stripe's own payment page, using the same Stripe keys as checkout. - To test, use Stripe's test card `4242 4242 4242 4242`. The Stripe product and price for each plan are created automatically the first time someone subscribes to it. - When the trial ends with no paid plan, AI, new stores and publishing are switched off and live stores go offline. Nothing is deleted. ## Published stores - A published store opens at `.`, for example http://luna-skin.localhost:8000. - On a local machine this works without any setup, because browsers send every `*.localhost` address to your own computer. - Once hosted, set `STOREFRONT_DOMAIN` in the settings file (for example `mystores.my`), and point `*.mystores.my` at the server. - Shoppers see a saved copy of the design. The merchant's later changes go live only after "Publish changes". Products, prices and stock are always live. - The owner's private preview stays at `/stores//preview`. ## Payments - Checkout uses Stripe's hosted payment page, so card details never touch this app. - Put your Stripe **test** keys in `.env.local`: ``` STRIPE_KEY=pk_test_... STRIPE_SECRET=sk_test_... ``` - To test a payment, use Stripe's test card `4242 4242 4242 4242`, any future date and any 3 digits. - `STRIPE_WEBHOOK_SECRET` is optional on a local machine. The app also confirms a payment when the shopper returns from Stripe. The webhook address is `/stripe/webhook`. - All payments go through one interface (`app/Commerce/Payments/PaymentGateway.php`), so another provider can be added without changing the checkout. - Money is always saved in sen (whole numbers). ## Plans and limits Starting numbers, to 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 | ## Where things are in the code | Thing | Location | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Pages (URLs) | `routes/web.php` | | Store model | `app/Models/Store.php` | | Store screens logic | `app/Http/Controllers/StoreController.php` | | Preview and sample design logic | `app/Http/Controllers/StoreDesignController.php` | | Store categories, languages, statuses | `app/Enums/` | | Store form rules | `app/Http/Requests/Stores/CreateStoreRequest.php` | | Store plan rules and checker | `app/StorePlan/` | | AI layer and providers | `app/Ai/`, `config/ai.php` | | AI prompts, generation, chat edits | `app/StorePlan/Ai/` | | Background AI job | `app/Jobs/RunStoreGeneration.php` | | Products | `app/Models/Product.php`, `app/Http/Controllers/ProductController.php`, `resources/js/pages/stores/products/` | | Storefront Shop and product pages | `resources/js/storefront/pages/` | | Plan limits and usage | `config/plans.php`, `app/Billing/UsageLimits.php` | | Dashboard screens | `resources/js/pages/dashboard.tsx`, `resources/js/pages/stores/` | | Storefront renderer and sections | `resources/js/storefront/` | | Database tables | `database/migrations/` | | Tests | `tests/Feature/` | ## Branches - `main` is the stable copy. - Each new step gets its own branch (for example `feature/ai-generation`) and is merged into `main` when finished and tested. ## Project files to know - [PROGRESS.md](PROGRESS.md): the plan, decisions, current step and session log. Updated after every work session. - [CLAUDE.md](CLAUDE.md): instructions for the AI assistant used in development. ## License Private. All rights reserved. | Cart, checkout and payments | `app/Commerce/` | | Live store or preview | `app/Storefront/Storefront.php`, top of `routes/web.php` | | Plans, trial and billing | `app/Billing/`, `app/Models/Plan.php`, `resources/js/pages/billing/` | | Orders for the merchant | `app/Http/Controllers/OrderController.php`, `resources/js/pages/stores/orders/` |