# 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 | Next | | 7 | Malaysia features: FPX, DuitNow, EasyParcel, WhatsApp | Not started | | 8 | Discounts and product options: codes, variants, bundles | Not started | | 9 | 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" - 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 - 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" 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`. ## 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` | | Orders for the merchant | `app/Http/Controllers/OrderController.php`, `resources/js/pages/stores/orders/` |