|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+# AI Commerce
|
|
|
2
|
+
|
|
|
3
|
+An AI store generator for ecommerce. A customer describes their brand, and the AI builds a complete online store for them.
|
|
|
4
|
+
|
|
|
5
|
+- **Customers:** first-time founders and existing merchants
|
|
|
6
|
+- **Market:** Malaysia first
|
|
|
7
|
+- **Status:** in development, running on a local machine only (not hosted yet)
|
|
|
8
|
+
|
|
|
9
|
+> The full plan, all decisions and the current step are in [PROGRESS.md](PROGRESS.md). Read that file first when you continue work.
|
|
|
10
|
+
|
|
|
11
|
+## Current status
|
|
|
12
|
+
|
|
|
13
|
+| Step | What | Status |
|
|
|
14
|
+| ---- | ------------------------------------------------------- | ----------- |
|
|
|
15
|
+| 0 | Prepare the local machine | Done |
|
|
|
16
|
+| 1 | Project foundation: login, create a store, dashboard | Done |
|
|
|
17
|
+| 2 | Store sections, renderer and preview | Done |
|
|
|
18
|
+| 3 | AI generation (Claude Sonnet 5.5, DeepSeek for edits) | Next |
|
|
|
19
|
+| 4 | Commerce: products, cart, checkout with Stripe Malaysia | Not started |
|
|
|
20
|
+| 5 | Publishing: subdomains, then custom domains | Not started |
|
|
|
21
|
+| 6 | Our own subscription billing | Not started |
|
|
|
22
|
+| 7 | Malaysia features: FPX, DuitNow, EasyParcel, WhatsApp | Not started |
|
|
|
23
|
+| 8 | Before launch: hosting, legal pages, backups | Not started |
|
|
|
24
|
+
|
|
|
25
|
+## What works today
|
|
|
26
|
+
|
|
|
27
|
+- Register, log in, log out, email verification and two-factor login
|
|
|
28
|
+- Create a store (name, category, language, description)
|
|
|
29
|
+- Dashboard that lists your own stores. Other people's stores show "not found"
|
|
|
30
|
+- A saved design for each store, called a **store plan**
|
|
|
31
|
+- 10 storefront sections, each with 2 layouts: header, hero, product grid, featured product, about, testimonials, FAQ, newsletter, contact, footer
|
|
|
32
|
+- A live preview of the storefront inside the dashboard, at desktop and mobile size
|
|
|
33
|
+- An "Apply sample design" button that fills a store with a hand-written plan (temporary, until AI generation is built)
|
|
|
34
|
+
|
|
|
35
|
+Known gaps: no phone menu for header links yet, images are placeholders, and the newsletter form does not save sign-ups.
|
|
|
36
|
+
|
|
|
37
|
+## Tech stack
|
|
|
38
|
+
|
|
|
39
|
+| Part | Choice |
|
|
|
40
|
+| --------------- | ------------------------------------------------------------- |
|
|
|
41
|
+| Backend | Laravel 13 on PHP 8.4 (8.3 also supported) |
|
|
|
42
|
+| Frontend | React 19 + TypeScript, linked to Laravel with Inertia 3 |
|
|
|
43
|
+| Styling | Tailwind CSS v4 + shadcn/ui |
|
|
|
44
|
+| Login | Laravel Fortify |
|
|
|
45
|
+| Database | MySQL (tests use an in-memory SQLite database) |
|
|
|
46
|
+| Background jobs | Laravel queues, database driver |
|
|
|
47
|
+| Payments | Stripe Malaysia (Step 4) |
|
|
|
48
|
+| AI | Claude Sonnet 5.5 for generation, DeepSeek for edits (Step 3) |
|
|
|
49
|
+
|
|
|
50
|
+## Set up on a new machine
|
|
|
51
|
+
|
|
|
52
|
+You need: PHP 8.3 or 8.4, Composer, Node 24 + npm, and MySQL.
|
|
|
53
|
+
|
|
|
54
|
+1. Get the code:
|
|
|
55
|
+
|
|
|
56
|
+ ```bash
|
|
|
57
|
+ git clone https://git.mirfalah.my/mirfalah-tech/ai_commerce.git
|
|
|
58
|
+ ```
|
|
|
59
|
+
|
|
|
60
|
+2. Create an empty MySQL database named `ai_commerce`.
|
|
|
61
|
+
|
|
|
62
|
+3. Inside the project folder, copy the example settings file:
|
|
|
63
|
+
|
|
|
64
|
+ ```bash
|
|
|
65
|
+ cp .env.example .env
|
|
|
66
|
+ ```
|
|
|
67
|
+
|
|
|
68
|
+4. Open `.env` and set the database lines (the example file uses SQLite by default):
|
|
|
69
|
+
|
|
|
70
|
+ ```
|
|
|
71
|
+ APP_NAME="AI Commerce"
|
|
|
72
|
+ DB_CONNECTION=mysql
|
|
|
73
|
+ DB_HOST=127.0.0.1
|
|
|
74
|
+ DB_PORT=3306
|
|
|
75
|
+ DB_DATABASE=ai_commerce
|
|
|
76
|
+ DB_USERNAME=your_mysql_user
|
|
|
77
|
+ DB_PASSWORD=your_mysql_password
|
|
|
78
|
+ ```
|
|
|
79
|
+
|
|
|
80
|
+5. Install everything, create the tables and build the frontend:
|
|
|
81
|
+
|
|
|
82
|
+ ```bash
|
|
|
83
|
+ composer run setup
|
|
|
84
|
+ ```
|
|
|
85
|
+
|
|
|
86
|
+6. Optional: create a local test user:
|
|
|
87
|
+
|
|
|
88
|
+ ```bash
|
|
|
89
|
+ php artisan db:seed
|
|
|
90
|
+ ```
|
|
|
91
|
+
|
|
|
92
|
+ The email is in `database/seeders/DatabaseSeeder.php` and the password is in `database/factories/UserFactory.php`.
|
|
|
93
|
+
|
|
|
94
|
+The `.env` file holds passwords and API keys. It is never uploaded to the repository, so each machine needs its own.
|
|
|
95
|
+
|
|
|
96
|
+## Run the app
|
|
|
97
|
+
|
|
|
98
|
+If your default `php` is not 8.3 or 8.4, point the terminal at the right one first. On the main development machine:
|
|
|
99
|
+
|
|
|
100
|
+```bash
|
|
|
101
|
+export PATH="/opt/homebrew/opt/php@8.4/bin:$PATH"
|
|
|
102
|
+```
|
|
|
103
|
+
|
|
|
104
|
+Then start the app (web server, queue worker and frontend together):
|
|
|
105
|
+
|
|
|
106
|
+```bash
|
|
|
107
|
+composer run dev
|
|
|
108
|
+```
|
|
|
109
|
+
|
|
|
110
|
+Open http://localhost:8000.
|
|
|
111
|
+
|
|
|
112
|
+Emails, such as verification links, are not sent. They are written to `storage/logs/laravel.log`.
|
|
|
113
|
+
|
|
|
114
|
+## Tests and code checks
|
|
|
115
|
+
|
|
|
116
|
+| Task | Command |
|
|
|
117
|
+| ----------------------------------------------------------------- | ---------------------------------------------- |
|
|
|
118
|
+| Run all tests | `php artisan test` |
|
|
|
119
|
+| Rebuild the frontend (needed before tests after changing screens) | `npm run build` |
|
|
|
120
|
+| Fix PHP code style | `composer lint` |
|
|
|
121
|
+| Check PHP types | `vendor/bin/phpstan analyse --memory-limit=1G` |
|
|
|
122
|
+| Check frontend style | `npm run check` |
|
|
|
123
|
+| Check frontend types | `npm run types:check` |
|
|
|
124
|
+
|
|
|
125
|
+## How a store design works
|
|
|
126
|
+
|
|
|
127
|
+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**.
|
|
|
128
|
+
|
|
|
129
|
+- A store plan is JSON saved in the `plan` column of the `stores` table.
|
|
|
130
|
+- It has a **theme** (8 colours, a heading font, a body font, corner roundness) and an ordered list of **sections**.
|
|
|
131
|
+- Each section has an `id`, a `type`, a `variant` (the layout) and `content` (the text).
|
|
|
132
|
+- `app/StorePlan/PlanSchema.php` is the one place that says what is allowed.
|
|
|
133
|
+- `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.
|
|
|
134
|
+- The storefront uses its own colours (CSS variables starting with `--sf-`), so it never mixes with the dashboard colours.
|
|
|
135
|
+
|
|
|
136
|
+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`.
|
|
|
137
|
+
|
|
|
138
|
+## AI: easy to change the model
|
|
|
139
|
+
|
|
|
140
|
+Changing from Claude to another AI model must be a settings change, not a code rewrite. This is built in Step 3:
|
|
|
141
|
+
|
|
|
142
|
+- All AI calls go through one place in the code, the "AI layer".
|
|
|
143
|
+- Each provider (Claude, DeepSeek, others later) is one small driver class.
|
|
|
144
|
+- Each task picks its provider and model in `.env`:
|
|
|
145
|
+
|
|
|
146
|
+ ```
|
|
|
147
|
+ AI_GENERATE_PROVIDER=claude
|
|
|
148
|
+ AI_GENERATE_MODEL=claude-sonnet-5-5
|
|
|
149
|
+ AI_EDIT_PROVIDER=deepseek
|
|
|
150
|
+ AI_EDIT_MODEL=deepseek-chat
|
|
|
151
|
+ ```
|
|
|
152
|
+
|
|
|
153
|
+- Every AI result is checked by `PlanValidator`, so a weaker model cannot break a store.
|
|
|
154
|
+
|
|
|
155
|
+## Plans and limits
|
|
|
156
|
+
|
|
|
157
|
+Starting numbers, to adjust after real usage.
|
|
|
158
|
+
|
|
|
159
|
+| Plan | Price / month | Stores | Full regenerations / month | AI edits / month |
|
|
|
160
|
+| -------------------- | ------------- | ------ | -------------------------- | ---------------- |
|
|
|
161
|
+| Free trial (14 days) | RM0 | 1 | 2 in total | 30 in total |
|
|
|
162
|
+| Starter | RM39 | 1 | 3 | 100 |
|
|
|
163
|
+| Growth | RM99 | 3 | 10 | 500 |
|
|
|
164
|
+| Pro | RM249 | 10 | 30 | 2,000 |
|
|
|
165
|
+
|
|
|
166
|
+## Where things are in the code
|
|
|
167
|
+
|
|
|
168
|
+| Thing | Location |
|
|
|
169
|
+| ------------------------------------- | ---------------------------------------------------------------- |
|
|
|
170
|
+| Pages (URLs) | `routes/web.php` |
|
|
|
171
|
+| Store model | `app/Models/Store.php` |
|
|
|
172
|
+| Store screens logic | `app/Http/Controllers/StoreController.php` |
|
|
|
173
|
+| Preview and sample design logic | `app/Http/Controllers/StoreDesignController.php` |
|
|
|
174
|
+| Store categories, languages, statuses | `app/Enums/` |
|
|
|
175
|
+| Store form rules | `app/Http/Requests/Stores/CreateStoreRequest.php` |
|
|
|
176
|
+| Store plan rules and checker | `app/StorePlan/` |
|
|
|
177
|
+| Dashboard screens | `resources/js/pages/dashboard.tsx`, `resources/js/pages/stores/` |
|
|
|
178
|
+| Storefront renderer and sections | `resources/js/storefront/` |
|
|
|
179
|
+| Database tables | `database/migrations/` |
|
|
|
180
|
+| Tests | `tests/Feature/` |
|
|
|
181
|
+
|
|
|
182
|
+## Branches
|
|
|
183
|
+
|
|
|
184
|
+- `main` is the stable copy.
|
|
|
185
|
+- Each new step gets its own branch (for example `feature/ai-generation`) and is merged into `main` when finished and tested.
|
|
|
186
|
+
|
|
|
187
|
+## Project files to know
|
|
|
188
|
+
|
|
|
189
|
+- [PROGRESS.md](PROGRESS.md): the plan, decisions, current step and session log. Updated after every work session.
|
|
|
190
|
+- [CLAUDE.md](CLAUDE.md): instructions for the AI assistant used in development.
|
|
|
191
|
+
|
|
|
192
|
+## License
|
|
|
193
|
+
|
|
|
194
|
+Private. All rights reserved.
|