github-copilot/site-fullstack/.github/instructions/ecommerce-fullstack.instructions.md

name, description

name	description
ecommerce-fullstack	Use when building or extending a FastAPI backend, React frontend, Next.js storefront, admin panel, back office, PostgreSQL schema, or AGENTS.md workflow for an ecommerce project.

Ecommerce Full-Stack Rules

Always decide these first

• Is the target a monorepo or split frontend and backend repos.
• Is the project greenfield or an extension of an existing codebase.
• Is customer authentication required, optional, or excluded.
• Does the storefront need a server-backed cart or an anonymous browser cart.
• Which admin roles are needed: owner, manager, editor, support, content admin.

If the command lacks detail

• Do not silently assume missing business and product details.
• Ask a short batch of concrete questions before implementation.
• Keep the first clarification batch focused on the current step only.
• For new builds, prefer asking about repo mode, niche, audience, required pages, auth, cart, admin scope, integrations, and design direction.
• For existing projects, ask what must change, what must not change, and what flows are critical.
• For SEO, ask whether the user wants strategy, implementation, or review if that is unclear.
• For code review, ask whether to review the whole project or only a specific area when the scope is ambiguous.
• After clarification, write the answers into the relevant working file under .ai/ when appropriate.

.ai/STORE-BRIEF.md comes first

• Before writing application code, create or update .ai/STORE-BRIEF.md.
• Use .ai/STORE-BRIEF.md as the normalized source of truth for scope, assumptions, design, and implementation phases.
• For split repos, create a repo-local .ai/STORE-BRIEF.md and document the paired repo responsibilities.

AGENTS.md comes after the brief

• Create or update AGENTS.md from .ai/STORE-BRIEF.md before application code.
• For a monorepo, keep one root AGENTS.md that covers frontend, backend, shared types, environments, and delivery rules.
• For split repos, keep one AGENTS.md in the frontend repo and one in the backend repo, with cross-references to the other repo contract.

.backup is append-only

• Before any serious backend or frontend change, create a backup snapshot under .backup/.
• Use a timestamp with seconds in the snapshot name, for example .backup/20260520-143708-backend/.
• Treat .backup/ as append-only: create new snapshots there, but never modify or delete existing files or folders inside it.
• If there is no existing backend or frontend code to preserve yet, skip the backup instead of creating an empty snapshot.

Default technical baseline

• Backend: FastAPI, SQLAlchemy 2, Alembic, Pydantic v2, PostgreSQL.
• Frontend: React with Next.js by default.
• Prefer TypeScript on the frontend unless the user clearly asks otherwise.
• Prefer REST APIs with strong schema naming and version-safe contracts.

Environment and secrets baseline

• When the project needs configuration or secrets, create .env.template in the relevant repo root with every required variable and placeholder values instead of real credentials.
• Do not create .env with real secret data. The user should create the local .env file from .env.template and provide the real values themselves.
• Ensure .env is gitignored whenever env files are part of the workflow.
• For Python backends, centralize env parsing through pydantic-settings and a typed Settings model, typically in app/core/config.py, instead of calling os.getenv throughout the codebase.
• Only explicitly public frontend runtime variables may be exposed to client code. Backend secrets must remain server-side.

Architecture baseline

• Use a scalable, large-project folder structure on both backend and frontend.
• On the backend, keep responsibilities separated into dedicated areas such as api or routers, models, schemas, services, repositories or data-access, db, config or core, integrations, and tests.
• On the frontend, keep responsibilities separated into dedicated areas such as app or routes, pages or screens, features, entities or domain modules, components, api or services, hooks, lib, config, styles, and tests.
• Do not mix business logic into controllers, route handlers, or visual components when it belongs in services or domain modules.
• Do not dump unrelated files into one folder just because the project is small at the moment; keep the structure ready for growth.
• If the existing project architecture is already sound, extend it consistently instead of introducing a second competing structure.

Recommended FastAPI layout

backend/
	app/
		api/
			v1/
				routes/
				dependencies/
		core/
			config.py
			security.py
			logging.py
		db/
			base.py
			session.py
			migrations/
		models/
		schemas/
		repositories/
		services/
		integrations/
		utils/
		main.py
	tests/
		unit/
		integration/
		api/

Recommended Next.js or React layout

frontend/
	src/
		app/
		pages/
		widgets/
		features/
		entities/
		shared/
			ui/
			api/
			lib/
			hooks/
			config/
			styles/
		tests/
			unit/
			integration/
	public/

Recommended admin panel or back office layout

frontend/
	src/
		app/
			admin/
		widgets/
			dashboard/
			data-table/
			filters/
			forms/
		features/
			catalog-management/
			order-management/
			customer-management/
			role-management/
			promotion-management/
			content-management/
			media-management/
			settings-management/
		entities/
		shared/
			ui/
			api/
			lib/
			hooks/
			config/
			styles/
		tests/
			unit/
			integration/
			admin-e2e/

Recommended monorepo layout

project-root/
	.ai/
	.backup/
	AGENTS.md
	backend/
	frontend/
	shared/
		types/
		contracts/
		constants/
	infra/
		docker/
		scripts/
		ci/

Recommended split-repo layout

frontend-repo/
	.ai/
	.backup/
	AGENTS.md
	src/
	public/

backend-repo/
	.ai/
	.backup/
	AGENTS.md
	app/
	tests/
	alembic/

Layer responsibilities

• api or routes: HTTP endpoints, request wiring, dependency injection, transport-level validation, and response mapping.
• models: ORM entities and persistence-facing structures.
• schemas: Pydantic or transport schemas for request and response contracts.
• repositories: direct database access, query composition, and persistence operations.
• services: business logic, orchestration, transactions, pricing, auth rules, and workflow coordination.
• db: engine, session management, base metadata, migrations, and low-level database setup.
• core or config: settings, security primitives, logging, environment parsing, and app-wide bootstrapping concerns.
• integrations: payment gateways, CRM, ERP, email, storage, search, and other external systems.
• utils or lib: narrow shared helpers without core domain ownership.
• app or pages: route entry points, layouts, and page-level composition.
• widgets: larger UI blocks composed from features and shared components.
• features: user actions and business capabilities such as add-to-cart, checkout, login, or product filtering.
• entities: domain-oriented frontend state and presentation units for product, cart, category, order, user, and similar concepts.
• shared ui: reusable presentational components, design-system pieces, and layout primitives.
• shared api: frontend API clients, fetchers, query adapters, and typed transport helpers.
• hooks: reusable stateful client behavior and composition hooks.
• shared config: frontend runtime config, feature flags, env readers, and app constants.
• shared styles: tokens, themes, global styles, mixins, and animation primitives.
• tests: split by unit, integration, api, and ui or e2e depending on the stack.

Import and dependency rules

• Backend imports must be absolute from the app root, for example from app.utils.slug import build_slug, never relative like from ..utils import ....
• On the backend, do not add __all__ = ...; explicit direct imports are preferred.
• Backend dependency direction should stay one-way: api or routes -> services -> repositories -> models or db. Reverse imports are not allowed.
• Schemas may be shared between api and services, but models must not depend on api or route modules.
• Repositories may depend on models, db, and low-level query helpers, but should not contain HTTP, request, or UI concerns.
• Services may depend on repositories, schemas, integrations, and core config, but api modules should stay thin and not absorb business logic.
• Integrations should be wrapped behind service-facing interfaces or adapters rather than leaking vendor specifics through the whole codebase.
• Frontend imports should prefer a root alias from src, for example @/shared/ui/button or @/features/cart/model/use-cart, instead of deep relative chains like ../../../../shared/ui/button.
• On the frontend, page and app layers may depend on widgets, features, entities, and shared.
• Widgets may depend on features, entities, and shared.
• Features may depend on entities and shared, but not on pages or app-level modules.
• Entities may depend only on shared and their own local files.
• Shared must not import from features, entities, widgets, pages, or app.
• Avoid barrel exports when they hide ownership, create circular dependencies, or make imports less explicit.
• Tests may import the layer they test plus shared helpers, but production code must never depend on test modules.

Code quality baseline

• Always inspect pyproject.toml before deciding Python quality rules.
• Follow the configured static-analysis toolchain, especially mypy or ty, plus ruff and deptry when present.
• If mypy is configured, write code that satisfies the configured checks and aims for strict typing discipline.
• If ty is configured, follow its rules instead of assuming mypy.
• Keep dependency declarations coherent with actual imports and runtime usage.
• Prefer modern Python language features only when the configured interpreter version supports them.
• Prefer typed centralized settings access for env-driven configuration instead of ad hoc stringly-typed env lookups.
• For React and Next.js, keep code readable, explicit, and easy to maintain by another programmer.
• Avoid unnecessary abstraction, unstable render patterns, and hook misuse.
• Use newer framework features only when they are supported and clearly improve the code.

Testing baseline

• Inspect the existing backend and frontend test stack before adding tests.
• Prefer the project's current test runners and patterns.
• After meaningful backend or frontend changes, add or update automated tests where confidence would materially improve.
• Run the relevant tests instead of assuming they pass.
• If tests fail, fix the root cause and rerun.
• Do not weaken tests simply to force a green result.

Required commerce scope unless the user narrows it

• Storefront: home, category, catalog, product, cart, checkout or order request, auth, account when needed, content pages.
• Admin panel or back office: catalog management, taxonomy, attributes, filters, orders, users, roles, settings, content, media, and promo tools.
• Shared concerns: validation, search and filtering, sorting, empty states, loading states, error states, and audit-friendly admin actions.

Data and auth guidance

• PostgreSQL is the default database.
• Separate customer and staff permissions.
• Use RBAC in admin flows.
• For anonymous carts, use localStorage by default only when a simple client-side cart is enough.
• Prefer cookie or server-backed carts when the app needs SSR continuity, stricter pricing rules, or cross-device persistence.