Переглянути джерело

Add README

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feature/store-sections-renderer
fahmisaad 6 дні тому
джерело
коміт
97d89a06b8
1 змінених файлів з 194 додано та 0 видалено
  1. 194
    0
      README.md

+ 194
- 0
README.md Переглянути файл

@@ -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.

Завантаження…
Відмінити
Зберегти