# 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) | Built, waiting for a real test with API keys | | 4 | Commerce: products, cart, checkout with Stripe Malaysia | Not started | | 5 | Publishing: subdomains, then custom domains | Not started | | 6 | Our own subscription billing | Not started | | 7 | Malaysia features: FPX, DuitNow, EasyParcel, WhatsApp | Not started | | 8 | 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" - "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 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, copy the example settings file: ```bash cp .env.example .env ``` 4. Open `.env` and set the database lines (the example file uses SQLite by default): ``` APP_NAME="AI Commerce" DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=ai_commerce DB_USERNAME=your_mysql_user DB_PASSWORD=your_mysql_password ``` 5. Install everything, create the tables and build the frontend: ```bash composer run setup ``` 6. 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 `.env` file holds passwords and API keys. It is never uploaded to the repository, so each machine needs its own. ## 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) and an ordered list of **sections**. - Each section has an `id`, a `type`, a `variant` (the layout) and `content` (the text). - `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`: ``` 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` as `ANTHROPIC_API_KEY` and `DEEPSEEK_API_KEY`. - 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`. ## 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` | | 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.