@adlas/create-app 1.0.0

package/templates/docs/PROJECT_OVERVIEW.md

@@ -0,0 +1,302 @@
+# Berndorf E-Commerce Project - Overview
+
+## 📋 Project Summary
+
+This is a **Next.js 15 E-commerce Application** built as a Headless commerce solution with **Saleor GraphQL** backend. The project includes an online store, gift registry system, wishlist, user profile management, and other features.
+
+## 🛠️ Tech Stack
+
+### Core Technologies
+- **Framework**: Next.js 15.5.4 (App Router + Turbopack)
+- **React**: 19.2.0
+- **TypeScript**: 5.9.3 (Strict Mode)
+- **Node.js**: ES2017 target
+- **Package Manager**: pnpm
+
+### UI & Styling
+- **UI Library**: `@heroui/react` v2.8.5 (Primary UI library)
+- **Styling**: Tailwind CSS v4.1.17
+- **Icons**: 54 SVG icons in `/src/assets/icons`
+- **Fonts**:
+  - Raleway (Primary)
+  - Inter (Secondary)
+  - Water Brush (Decorative)
+
+### State Management & Data Fetching
+- **Global State**: Zustand v5.0.8
+- **Server State**: TanStack React Query v5.90.7
+- **Forms**: react-hook-form v7.66.0
+- **Validation**: Zod v4.1.12
+
+### Internationalization
+- **Library**: next-intl v4.5.0
+- **Languages**: English (en), German (de - default)
+- **Locale Files**: `/src/locales/en.json`, `/src/locales/de.json`
+
+### Backend Integration
+- **E-commerce**: Saleor GraphQL
+- **Auth**: @saleor/auth-sdk v1.0.3
+- **GraphQL**: TypedDocumentString pattern
+
+### Animation & Interactions
+- **Animation**: GSAP v3.13.0
+- **Carousel**: embla-carousel v8.6.0
+- **Maps**: react-leaflet v5.0.0
+
+### Development Tools
+- **Linting**: ESLint v9 (@antfu/eslint-config)
+- **Formatting**: Prettier v3.6.2 + prettier-plugin-tailwindcss
+- **Git Hooks**: Lefthook v1.13.6
+- **Type Checking**: TypeScript strict mode
+- **Commitlint**: Conventional commits
+
+---
+
+## 📁 Project Structure
+
+```
+berndorf-front/
+├── src/
+│   ├── app/                    # Next.js App Router
+│   │   ├── [locale]/           # Internationalized routes
+│   │   │   ├── (website)/      # Public pages (home, products, etc.)
+│   │   │   ├── (dashboard)/    # Protected pages (profile, gift-list, etc.)
+│   │   │   └── auth/           # Authentication pages
+│   │   ├── api/                # API routes
+│   │   └── providers.tsx       # App-level providers
+│   │
+│   ├── components/             # React Components
+│   │   ├── ui/                 # Base UI components (HeroUI extensions)
+│   │   ├── elements/           # Composite components
+│   │   ├── pages/              # Page-specific components
+│   │   ├── layout/             # Layout components (Navbar, Footer, etc.)
+│   │   ├── modals/             # Modal dialogs
+│   │   ├── auth/               # Authentication components
+│   │   └── icons/              # Generated icon components
+│   │
+│   ├── services/               # Service Layer (API + Business Logic)
+│   │   ├── {module}/
+│   │   │   ├── api/            # GraphQL API calls
+│   │   │   ├── actions/        # Server Actions
+│   │   │   ├── queries/        # GraphQL queries
+│   │   │   ├── helpers/        # Transformation functions
+│   │   │   ├── store/          # Zustand stores
+│   │   │   ├── types/          # TypeScript types
+│   │   │   └── index.ts        # Public exports
+│   │
+│   ├── hooks/                  # Custom React hooks
+│   ├── utils/                  # Utility functions
+│   ├── validations/            # Zod validation schemas
+│   ├── config/                 # App configuration
+│   ├── libs/                   # Third-party library configs
+│   ├── locales/                # Translation files
+│   ├── styles/                 # Global styles
+│   ├── types/                  # Global TypeScript types
+│   └── assets/                 # Static assets (icons, images)
+│
+├── public/                     # Public static files
+├── .env.example                # Environment variables template
+├── next.config.ts              # Next.js configuration
+├── tailwind.config (in globals.css)
+├── tsconfig.json               # TypeScript configuration
+├── lefthook.yml                # Git hooks configuration
+└── package.json                # Dependencies and scripts
+```
+
+---
+
+## 🎯 Key Features
+
+### 1. Authentication System
+- ✅ Login / Register
+- ✅ Password Reset
+- ✅ Protected Routes (Middleware)
+- ✅ HttpOnly Cookies (Saleor SDK)
+- ✅ Multi-step Registration Form
+
+### 2. E-commerce Features
+- ✅ Product Catalog with Category/Collection Filtering
+- ✅ Product Detail with Variants
+- ✅ Wishlist
+- ✅ Shopping Cart (in development)
+- ✅ Pricing & Inventory Management
+
+### 3. Gift Registry
+- ✅ Create Gift List
+- ✅ Add/Remove Products
+- ✅ Public Gift List URL
+- ✅ Share Gift List
+- ✅ Track Gift Purchases
+
+### 4. User Profile
+- ✅ Profile Management
+- ✅ My Requests
+- ✅ Gift List Management
+- ✅ Wishlist Management
+- ✅ Profile Image Upload
+
+### 5. Additional Features
+- ✅ News/Blog System (with Editor.js)
+- ✅ Store Locator (Leaflet Maps)
+- ✅ Newsletter Subscription
+- ✅ Contact Form
+- ✅ Care Instructions
+- ✅ Downloads Center
+- ✅ Multi-language Support (EN/DE)
+
+---
+
+## 🔑 Critical Information for AI
+
+### ⚠️ DO NOT Install New Packages
+This project uses **HeroUI** as the primary UI library. NEVER use other UI libraries (shadcn/ui, MUI, Ant Design, etc.).
+
+### ✅ Always Use Existing Components
+All necessary components are available in `/src/components/ui/`:
+- Button, Input, Select, Checkbox, etc.
+- Modal, Tabs, Carousel, etc.
+- Form components
+
+### 📚 Component Import Pattern
+```typescript
+// ✅ Correct
+import { Button, Input } from '@/components/ui';
+
+// ❌ Wrong - Don't install new packages
+import { Button } from 'shadcn/ui';
+import { TextField } from '@mui/material';
+```
+
+### 🎨 Styling Pattern
+```typescript
+// ✅ Use Tailwind classes
+<div className="flex flex-col gap-4 p-6">
+
+// ✅ Use utility classes from globals.css
+<div className="web-container">
+<div className="dashboard-container">
+
+// ❌ Don't use inline styles
+<div style={{ display: 'flex' }}>
+```
+
+### 📄 Page Implementation Rules
+1. **Server Components** by default
+2. **Client Components** only when state/hooks are needed (`'use client'`)
+3. **Data Fetching** in Server Component
+4. **Translations** with `getTranslations()` (server) or `useTranslations()` (client)
+
+---
+
+## 🌐 Environment Variables
+
+```bash
+# Saleor Backend
+SALEOR_SERVER_TOKEN=          # Server-side token
+NEXT_PUBLIC_SALEOR_API_URL=   # GraphQL endpoint
+
+# App Config
+NEXT_PUBLIC_SITE_URL=         # Base URL
+NODE_ENV=                     # development/production
+```
+
+---
+
+## 📦 Important Scripts
+
+```bash
+# Development
+pnpm dev              # Start dev server with Turbopack
+pnpm build            # Build for production
+pnpm start            # Start production server
+
+# Code Quality
+pnpm lint             # Run ESLint
+pnpm check:types      # TypeScript type checking
+pnpm check:i18n       # Validate translation keys
+
+# Testing
+pnpm test             # Run tests (if configured)
+```
+
+---
+
+## 🗂️ Service Modules
+
+Each service module in `/src/services/` follows a consistent structure:
+
+```
+services/{module}/
+├── api/              # executeGraphQL calls
+├── actions/          # Server Actions (mutations)
+├── queries/          # GraphQL query documents
+├── helpers/          # Transformation/normalization
+├── store/            # Zustand store (optional)
+├── types/            # TypeScript types
+└── index.ts          # Public exports
+```
+
+**Available Modules:**
+- `auth` - Authentication
+- `product` - Products
+- `category` - Categories
+- `collection` - Collections
+- `user` - User profile, wishlist, gift list
+- `news` - News/blog
+- `stores` - Physical stores
+- `newsletter` - Newsletter
+- `careInstructions` - Care guides
+- `downloads` - Downloads
+- `ads` - Advertisements
+- `home` - Home page data
+
+---
+
+## 🎨 Design System
+
+### Colors
+- **Primary**: Berndorf brand color
+- **Secondary**: Secondary actions
+- **Tertiary**: Custom tertiary palette (50-900)
+- **Info**: Custom info palette (25-900)
+
+### Typography
+- **Headers**: Raleway font
+- **Body**: Inter font
+- **Decorative**: Water Brush font
+
+### Spacing
+- **Container**: `.web-container`, `.dashboard-container`
+- **Gaps**: `gap-4`, `gap-6`, `gap-8`
+- **Padding**: `p-4`, `p-6`, `px-6 py-4`
+
+### Breakpoints
+```css
+/* Custom breakpoints */
+max-2xl: 1440px
+max-xl: 1280px
+max-lg: 1024px
+max-md: 768px
+max-sm: 640px
+max-xs: 375px
+```
+
+---
+
+## 🚀 Next Steps
+
+To implement new pages:
+1. 📖 Read `UI_COMPONENTS_GUIDE.md` for component usage
+2. 🏗️ Read `ARCHITECTURE_PATTERNS.md` for architectural patterns
+3. 📝 Read `IMPLEMENTATION_GUIDE.md` for step-by-step guide
+4. 🎨 Review Figma designs
+5. 💻 Start implementation following existing patterns
+
+---
+
+## 📞 Support
+
+For questions or issues:
+- Review existing code in the project
+- Read documentation files
+- Check HeroUI docs: https://www.heroui.com