Development path
The kit is a working store. Selling, catalog, checkout, and orders are already in it. You can run the store from the admin and never open the sections below.
Those sections grade a code change by how far it reaches. They are a classification, and each grade is optional. A store can stay on the admin grade for its whole life. When you do change the source, stop at the first grade that covers the change.
| Grade | What it covers | When you open it |
|---|---|---|
| Admin | Images, copy, prices, and switches the admin already saves | This is the store. No code. |
| Frontend | Color, fixed labels, header, and footer | The admin has no field for that chrome. |
| Page | What a route renders, or a new route | The current pages do not do that. |
| Backend | A new data model or a server-side rule | The current schema and Lambda functions cannot hold it. |
Run a code change against the local sandbox. npm run dev reloads storefront files. The sandbox process redeploys when files under amplify/ change. A file change on main or staging still needs that Amplify build to finish before customers see it. A save in the admin does not.
The file map for a specific edit is Where to change the storefront.
Admin
A first launch, or a new sandbox, is enough to sell. Import the sample catalog or enter the catalog by hand, then replace the images and the words in the admin. The admin stores those records. Saving them updates the running store. No new build.
| What you replace | Where |
|---|---|
| Store name, tagline, Site URL, logo, favicon | System → Site Settings |
| Sender, SMTP, IMAP, which order emails go out | System → Email Settings |
| Stripe, PayPal, Mock | System → Payment Settings |
| Currency, tax, guest checkout | System → Currency & tax |
| Which installed languages are public | System → Storefront Languages |
| Categories, brands, tags, products, photos, prices, stock | Product, category, brand, and tag screens |
| Homepage carousel, feature banners, inner-page hero, footer band, mobile menu image, why-choose rows | Content |
| Policy pages and journal posts | Blog |
| Campaigns and coupons | Marketing |
| Shipping templates and pickup points | Shipping template screens |
Product names, category copy, and blog posts are the language fields on those forms. The sample pack already fills them for the seven content languages. Procedures for each screen are in System and global settings and Catalog and products.
A picture, a price, a page of copy, or a switch the admin already has stays in this grade.
Frontend
Optional. Open this grade when the change is color, a fixed label, or a header and footer link. The pages, catalog, and checkout stay as they ship.
| What you change | Where |
|---|---|
| Color and spacing | src/styles/frontend/default/inkflow/. Start with the variables on .frontend-layout[data-theme="inkflow"] in globals.css. |
| Navigation, buttons, checkout labels | src/i18n/locales/frontend/ (default/shop/ for the storefront, default/bill/ for checkout). One file per content language. |
| Header and footer links | src/components/user/SiteNavigation.tsx and src/components/user/SiteFooter.tsx |
| Default logo and favicon shipped in the repository | src/config/themeAssets.ts and public/frontend/{theme}/other/ |
npm run dev picks up these files. Confirm the storefront at http://localhost:3000, then push. Customers see the change after that Hosting build finishes.
Site Settings can still replace the logo and favicon after you change the files. Carousel slides, feature banners, and page-layout images stay in Content. Leave those in the admin when the picture is content. Edit the stylesheet and the JSON when the change is the chrome around that content.
Page functionality
Optional. Open this grade when a route should render something the current pages do not, or when you add a route. The page still reads the catalog, banners, and copy the admin already stores. Skip it when the admin grade or the frontend grade already covers the change.
| What you change | Where |
|---|---|
| Homepage section order and which blocks appear | src/app/[locale]/page.tsx |
| A new marketing page | src/app/[locale]/<segment>/page.tsx, served at /{locale}/<segment> |
| Behavior of an existing storefront screen | The page.tsx for that route, and the components it imports |
src/app/[locale]/layout.tsx wraps storefront routes in the header and footer. A new page under [locale] already includes that shell. /admin stays outside it.
Keep images and translated copy in the admin when the page only needs a new arrangement of data you can already save there. Add a field to the page, and keep feeding it from Content or the catalog, before you add a new table.
Checkout, the cart, and account pages already exist. A change to how one of those screens looks or which fields it shows belongs in this layer. Payment capture, webhooks, and order status stay in the backend layer below. Read Architecture before editing that path.
Backend functionality
Optional. Open this grade when the change is a new data model or a server-side rule. The three grades above leave checkout, payments, orders, and mail as they ship. The sandbox watches amplify/ and redeploys that stack. Keep the sandbox terminal in the foreground until it reports ready, then reload the storefront.
| What you change | Where |
|---|---|
| A new field, model, or authorization rule | Amplify Gen 2 schema under amplify/ |
| Checkout, settlement, returns, admin mutations, outbound mail | Lambda under amplify/functions/ |
| A content language the schema and mail must accept | amplify/functions/shared/contentLanguages.ts, together with the storefront steps in Storefront locales |
AppSync and DynamoDB hold the catalog, carts, orders, and content. Lambda runs checkout, payment settlement, returns, admin mutations, and mail. S3 stores product and banner files under admin-pictures/. The Next.js app on Amplify Hosting is the storefront and the admin. That split is the architecture.
A new page that only rearranges products and banners does not need a schema change. Add a model when the admin must store something the current models cannot, or when a rule has to run on Lambda (a new charge, a new email, a write the storefront must not perform itself).
Payment webhooks stay on the shop domain: /api/webhooks/payments/stripe and /api/webhooks/payments/paypal. The app forwards them to Lambda. Leave that path in place unless the settlement flow itself is what you are changing.
How a change is graded
Match the change to one row. Finish that grade and stop. The later rows stay closed.
| Grade | You are changing | Verify |
|---|---|---|
| Admin | Images, copy, prices, and switches in the admin | Save, then reload http://localhost:3000. No build. |
| Frontend | Styles, labels, header, and footer | npm run dev, then the same URL. |
| Page | A page or a new route | The new path under a locale prefix, for example /en/your-page. |
| Backend | amplify/ schema or functions | Wait until the sandbox reports ready, then repeat the flow that uses the new field or rule. |
Use a short-lived branch for the edit. Verify on the sandbox, then on staging when you have that Hosting branch, then merge to main. Branch roles are in Local sandbox.
Next step
When that change is in the source, name its security boundary in Development Security before the commit. An admin-only change stays on the first grade and does not need that review.