Project structure

Reference

This page lists the real files MaShop writes into your GitHub repo and where each one lives. Your repo can hold two layers: a storefront scaffold that lands on your first prompt, and an optional backoffice template that lands only when the project is transactional. Both go into the same repo root. You own every file and can edit or delete any of them.

The storefront scaffold

The first time you prompt anything on a fresh project, the AI runs the scaffold_next_project tool, which commits 23 files to your repo so you get a runnable Next.js 15 project, not loose components. The commits are issued serially, so a fresh repo ends up with a complete, buildable tree.

This is the exact layout it writes:

package.json # Next 15.5.15, React 19, Tailwind v4, @supabase/ssr
tsconfig.json # strict mode, @/* path alias to repo root
next.config.ts # AVIF/WebP images, eslint.ignoreDuringBuilds: true
next-env.d.ts
postcss.config.mjs
tailwind.config.ts # brand color token #0052FF
eslint.config.mjs.gitignore.env.local.example # Supabase + Stripe env var names, all blank
netlify.toml # build = npm run build, @netlify/plugin-nextjs
README.md
app/
 layout.tsx # root layout, export const dynamic = 'force-dynamic'
 globals.css # Tailwind import + --brand token
 page.tsx # placeholder home (Header + Footer)
 icon.tsx # dynamic favicon via next/og ImageResponse
 api/
 checkout/route.ts # Stripe placeholder, returns HTTP 501
components/
 Header.tsx
 Footer.tsx
lib/
 supabase.ts # createClient from NEXT_PUBLIC_SUPABASE_* env vars
 utils.ts # cn() and formatPrice(cents)
 types.ts # Product, Category (money in integer cents)
 products.ts # getProducts, getProductBySlug, getCategories
 seo.ts # productMetadata + productJsonLd helpers

Key scaffold files

File	What it does
app/layout.tsx	Sets export const dynamic = 'force-dynamic', which every page inherits. Pages render at request time, so data stays fresh and the build never crashes prerendering a page that queries Supabase.
lib/products.ts	Typed read functions (getProducts, getProductBySlug, getCategories) that query your own Supabase. Server Components call these. The AI extends them rather than rewriting them.
lib/seo.ts	Builds Next.js Metadata (Open Graph, Twitter card, canonical) and a JSON-LD Product object per product.
app/api/checkout/route.ts	A placeholder POST handler that returns HTTP 501 with the message "Checkout not yet configured." until you prompt the AI to wire your payment provider.
app/icon.tsx	Generates a 512x512 favicon at request time from the project name's first letter. Replace it by dropping app/icon.png and deleting this file, or ask the AI.

The backoffice template

If your project is transactional, MaShop also installs a full Next.js 15 admin backoffice into the same repo. The decision is made by shouldInstallBackoffice: a prompt about a shop, store, orders, products, restaurant, booking, subscription, or ticketing installs it; a prompt about a portfolio, landing page, blog, or resume does not. The backoffice is a heavy surface, so it is intent-driven, not always on.

During provisioning the whole template tree is pushed to your repo as a single commit using the GitHub Git Data API. Its top-level layout:

src/
 app/
 (backoffice)/ # the admin shell + every page (route group)
 api/ # REST endpoints, one folder per resource
 auth/ # staff sign-in
 layout.tsx
 page.tsx
 globals.css
 lib/ # domain logic: queries, mutations, types
 components/ # shell, ui, editor, charts, skeletons, more
 hooks/ # shared React hooks
 i18n/ # locale dictionaries
 types/database.ts # Supabase types for the admin schema
supabase/migrations/ # 22 SQL migrations for your admin schema
playwright/ # tap-target + responsive tests
netlify.toml
vercel.json # forces pnpm install --ignore-workspace

Admin pages (src/app/(backoffice))

Every admin page lives under the (backoffice) route group, which supplies the shared shell (navigation rail, top bar, mobile tabs). The pages are grouped by domain:

• Catalog: products, categories, attributes, collections, inventory.
• Commerce: orders, customers, coupons, segments, reviews.
• Analytics: a dashboard plus an analytics section.
• Content: the blog with its categories, comments, and a per-post editor.
• Settings: general, branding, domains, localization, notifications, integrations, security, and staff sub-pages.
• SEO: per-page SEO management under seo.

Each domain has matching REST endpoints under src/app/api, for example /api/products, /api/orders, and /api/blog.

Domain logic (src/lib)

Business logic is split into one module per domain: products, orders, customers, coupons, shipping, inventory, blog, payments, analytics, settings, and more. Each module typically exposes:

• queries.ts holds read functions.
• mutations.ts holds create, update, and delete functions.
• types.ts holds the domain's TypeScript types.

Shared helpers also live here: the Supabase clients (browser, server, admin) in lib/supabase, money and date formatting in lib/format, Zod schemas in lib/validations, navigation config in lib/nav, and the icon re-export point at lib/icons.tsx.

Components (src/components)

• shell/ holds the navigation rail, top bar, global search, bulk-action bar, and mobile navigation.
• ui/ holds reusable primitives such as ResponsiveSheet, ConfirmDialog, FiltersPopover, and the toast helper.
• editor/ holds the Tiptap blog editor and its custom blocks.
• analytics/, charts/, skeletons/ hold dashboard widgets, chart wrappers, and loading states.

Where this fits

• Tech stack and conventions covers the rules the generated code follows.
• Connect your Supabase explains how the admin schema reaches your database.
• Data reference lists the tables, RPCs, and RLS the migrations create.