@adlas/create-app 1.0.0

package/templates/docs/ARCHITECTURE_PATTERNS.md

@@ -0,0 +1,927 @@
+# Architecture Patterns
+
+Comprehensive guide to architectural patterns used in the Berndorf e-commerce project. Follow these patterns for consistency and maintainability.
+
+## Table of Contents
+
+1. [Service Module Pattern](#service-module-pattern)
+2. [State Management with Zustand](#state-management-with-zustand)
+3. [Data Fetching with React Query](#data-fetching-with-react-query)
+4. [Form Patterns](#form-patterns)
+5. [Validation Patterns](#validation-patterns)
+6. [Internationalization (i18n)](#internationalization-i18n)
+7. [Authentication Patterns](#authentication-patterns)
+8. [API Communication](#api-communication)
+
+---
+
+## Service Module Pattern
+
+All features follow a consistent service module structure for organization and maintainability.
+
+### Directory Structure
+
+```
+src/services/[feature]/
+├── index.ts                 # Public exports
+├── api/                     # API client functions
+│   └── [feature].api.ts
+├── queries/                 # React Query hooks
+│   └── [feature].queries.ts
+├── hooks/                   # Custom hooks
+│   └── use[Feature].ts
+├── types/                   # TypeScript types
+│   └── [feature].types.ts
+├── actions/                 # Server actions
+│   └── [feature].actions.ts
+├── store/                   # Zustand stores
+│   └── [feature].store.ts
+├── constants/               # Constants
+│   └── [feature].constants.ts
+└── helpers/                 # Helper functions
+    └── [feature].helpers.ts
+```
+
+### Complete Example: Product Service Module
+
+#### 1. Index File (Public API)
+
+**File:** `src/services/product/index.ts`
+
+```typescript
+// Export all public APIs
+export * from './api/product.api';
+export * from './queries/product.queries';
+export * from './hooks/useProducts';
+export * from './types/product.types';
+export * from './actions/product.actions';
+export * from './store/product.store';
+export * from './constants/product.constants';
+export * from './helpers/product.helpers';
+```
+
+#### 2. Types Definition
+
+**File:** `src/services/product/types/product.types.ts`
+
+```typescript
+// API Response types
+export interface ProductApiResponse {
+  id: string;
+  name: string;
+  description: string;
+  price: number;
+  images: string[];
+  category: string;
+  stock: number;
+  createdAt: string;
+}
+
+// Frontend model types
+export interface Product {
+  id: string;
+  name: string;
+  description: string;
+  price: number;
+  formattedPrice: string;
+  images: string[];
+  primaryImage: string;
+  category: string;
+  inStock: boolean;
+  createdAt: Date;
+}
+
+// Request types
+export interface CreateProductRequest {
+  name: string;
+  description: string;
+  price: number;
+  categoryId: string;
+}
+
+// Filter types
+export interface ProductFilters {
+  category?: string;
+  minPrice?: number;
+  maxPrice?: number;
+  inStock?: boolean;
+}
+```
+
+#### 3. API Client
+
+**File:** `src/services/product/api/product.api.ts`
+
+```typescript
+import { apiRequest } from '@/lib/apiRequest';
+import type { Product, ProductApiResponse, CreateProductRequest, ProductFilters } from '../types/product.types';
+import { transformProductResponse } from '../helpers/product.helpers';
+
+/**
+ * Fetch all products with optional filters
+ */
+export async function getProducts(filters?: ProductFilters): Promise<Product[]> {
+  const queryParams = new URLSearchParams();
+
+  if (filters?.category) queryParams.append('category', filters.category);
+  if (filters?.minPrice) queryParams.append('minPrice', String(filters.minPrice));
+  if (filters?.maxPrice) queryParams.append('maxPrice', String(filters.maxPrice));
+  if (filters?.inStock !== undefined) queryParams.append('inStock', String(filters.inStock));
+
+  const url = `/api/products${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+
+  const response = await apiRequest<ProductApiResponse[]>({
+    url,
+    method: 'GET',
+  });
+
+  return response.map(transformProductResponse);
+}
+
+/**
+ * Fetch a single product by ID
+ */
+export async function getProduct(id: string): Promise<Product> {
+  const response = await apiRequest<ProductApiResponse>({
+    url: `/api/products/${id}`,
+    method: 'GET',
+  });
+
+  return transformProductResponse(response);
+}
+
+/**
+ * Create a new product
+ */
+export async function createProduct(data: CreateProductRequest): Promise<Product> {
+  const response = await apiRequest<ProductApiResponse>({
+    url: '/api/products',
+    method: 'POST',
+    data,
+  });
+
+  return transformProductResponse(response);
+}
+
+/**
+ * Update an existing product
+ */
+export async function updateProduct(id: string, data: Partial<CreateProductRequest>): Promise<Product> {
+  const response = await apiRequest<ProductApiResponse>({
+    url: `/api/products/${id}`,
+    method: 'PATCH',
+    data,
+  });
+
+  return transformProductResponse(response);
+}
+
+/**
+ * Delete a product
+ */
+export async function deleteProduct(id: string): Promise<void> {
+  await apiRequest<void>({
+    url: `/api/products/${id}`,
+    method: 'DELETE',
+  });
+}
+```
+
+#### 4. Helper Functions
+
+**File:** `src/services/product/helpers/product.helpers.ts`
+
+```typescript
+import type { Product, ProductApiResponse } from '../types/product.types';
+
+/**
+ * Transform API response to frontend model
+ */
+export function transformProductResponse(data: ProductApiResponse): Product {
+  return {
+    id: data.id,
+    name: data.name,
+    description: data.description,
+    price: data.price,
+    formattedPrice: formatPrice(data.price),
+    images: data.images,
+    primaryImage: data.images[0] || '/placeholder.jpg',
+    category: data.category,
+    inStock: data.stock > 0,
+    createdAt: new Date(data.createdAt),
+  };
+}
+
+/**
+ * Format price with currency
+ */
+export function formatPrice(price: number): string {
+  return new Intl.NumberFormat('de-AT', {
+    style: 'currency',
+    currency: 'EUR',
+  }).format(price);
+}
+
+/**
+ * Check if product is new (created within last 30 days)
+ */
+export function isNewProduct(createdAt: Date): boolean {
+  const thirtyDaysAgo = new Date();
+  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
+  return createdAt > thirtyDaysAgo;
+}
+```
+
+#### 5. React Query Hooks
+
+**File:** `src/services/product/queries/product.queries.ts`
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import type { ProductFilters, CreateProductRequest } from '../types/product.types';
+import {
+  getProducts,
+  getProduct,
+  createProduct,
+  updateProduct,
+  deleteProduct,
+} from '../api/product.api';
+
+// Query Keys
+export const productKeys = {
+  all: ['products'] as const,
+  lists: () => [...productKeys.all, 'list'] as const,
+  list: (filters?: ProductFilters) => [...productKeys.lists(), filters] as const,
+  details: () => [...productKeys.all, 'detail'] as const,
+  detail: (id: string) => [...productKeys.details(), id] as const,
+};
+
+/**
+ * Fetch all products with optional filters
+ */
+export function useProductsQuery(filters?: ProductFilters) {
+  return useQuery({
+    queryKey: productKeys.list(filters),
+    queryFn: () => getProducts(filters),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  });
+}
+
+/**
+ * Fetch a single product by ID
+ */
+export function useProductQuery(id: string) {
+  return useQuery({
+    queryKey: productKeys.detail(id),
+    queryFn: () => getProduct(id),
+    enabled: !!id,
+  });
+}
+
+/**
+ * Create a new product
+ */
+export function useCreateProductMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createProduct,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: productKeys.lists() });
+      toast.success('Product created successfully');
+    },
+    onError: (error: Error) => {
+      toast.error(error.message || 'Failed to create product');
+    },
+  });
+}
+
+/**
+ * Update an existing product
+ */
+export function useUpdateProductMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: Partial<CreateProductRequest> }) =>
+      updateProduct(id, data),
+    onSuccess: (_, variables) => {
+      queryClient.invalidateQueries({ queryKey: productKeys.lists() });
+      queryClient.invalidateQueries({ queryKey: productKeys.detail(variables.id) });
+      toast.success('Product updated successfully');
+    },
+    onError: (error: Error) => {
+      toast.error(error.message || 'Failed to update product');
+    },
+  });
+}
+
+/**
+ * Delete a product
+ */
+export function useDeleteProductMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: deleteProduct,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: productKeys.lists() });
+      toast.success('Product deleted successfully');
+    },
+    onError: (error: Error) => {
+      toast.error(error.message || 'Failed to delete product');
+    },
+  });
+}
+```
+
+#### 6. Custom Hooks
+
+**File:** `src/services/product/hooks/useProducts.ts`
+
+```typescript
+import { useMemo } from 'react';
+import { useProductsQuery } from '../queries/product.queries';
+import type { ProductFilters } from '../types/product.types';
+import { isNewProduct } from '../helpers/product.helpers';
+
+export function useProducts(filters?: ProductFilters) {
+  const { data, isLoading, error } = useProductsQuery(filters);
+
+  const products = useMemo(() => {
+    if (!data) return [];
+
+    return data.map(product => ({
+      ...product,
+      isNew: isNewProduct(product.createdAt),
+    }));
+  }, [data]);
+
+  const inStockProducts = useMemo(
+    () => products.filter(p => p.inStock),
+    [products],
+  );
+
+  const newProducts = useMemo(
+    () => products.filter(p => p.isNew),
+    [products],
+  );
+
+  return {
+    products,
+    inStockProducts,
+    newProducts,
+    isLoading,
+    error,
+    isEmpty: products.length === 0,
+  };
+}
+```
+
+#### 7. Server Actions
+
+**File:** `src/services/product/actions/product.actions.ts`
+
+```typescript
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import type { CreateProductRequest } from '../types/product.types';
+
+export async function createProductAction(data: CreateProductRequest) {
+  try {
+    const response = await fetch(`${process.env.API_URL}/products`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(data),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      return { success: false, error: error.message };
+    }
+
+    const product = await response.json();
+
+    // Revalidate relevant paths
+    revalidatePath('/products');
+    revalidatePath(`/products/${product.id}`);
+
+    return { success: true, data: product };
+  } catch (error) {
+    console.error('Create product action error:', error);
+    return { success: false, error: 'Failed to create product' };
+  }
+}
+
+export async function deleteProductAction(id: string) {
+  try {
+    const response = await fetch(`${process.env.API_URL}/products/${id}`, {
+      method: 'DELETE',
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      return { success: false, error: error.message };
+    }
+
+    // Revalidate relevant paths
+    revalidatePath('/products');
+
+    return { success: true };
+  } catch (error) {
+    console.error('Delete product action error:', error);
+    return { success: false, error: 'Failed to delete product' };
+  }
+}
+```
+
+#### 8. Zustand Store
+
+**File:** `src/services/product/store/product.store.ts`
+
+```typescript
+import { create } from 'zustand';
+import type { ProductFilters } from '../types/product.types';
+
+interface ProductStore {
+  filters: ProductFilters;
+  selectedProductId: string | null;
+  setFilters: (filters: ProductFilters) => void;
+  setSelectedProductId: (id: string | null) => void;
+  resetFilters: () => void;
+  reset: () => void;
+}
+
+const initialState = {
+  filters: {},
+  selectedProductId: null,
+};
+
+export const useProductStore = create<ProductStore>((set) => ({
+  ...initialState,
+
+  setFilters: (filters) => set({ filters }),
+
+  setSelectedProductId: (id) => set({ selectedProductId: id }),
+
+  resetFilters: () => set({ filters: {} }),
+
+  reset: () => set(initialState),
+}));
+```
+
+#### 9. Constants
+
+**File:** `src/services/product/constants/product.constants.ts`
+
+```typescript
+export const PRODUCT_CONSTANTS = {
+  MAX_IMAGES: 5,
+  MIN_PRICE: 0,
+  MAX_PRICE: 10000,
+  PRICE_STEP: 0.01,
+  NEW_PRODUCT_DAYS: 30,
+} as const;
+
+export const PRODUCT_CATEGORIES = [
+  { id: 'cutlery', label: 'Cutlery' },
+  { id: 'cookware', label: 'Cookware' },
+  { id: 'tableware', label: 'Tableware' },
+] as const;
+```
+
+---
+
+## State Management with Zustand
+
+Use Zustand for global state that needs to be shared across components.
+
+### When to Use Zustand
+
+- User authentication state
+- Shopping cart
+- UI preferences (theme, language)
+- Filter/search state across pages
+- Global modals/overlays
+
+### Zustand Store Pattern
+
+```typescript
+import { create } from 'zustand';
+
+interface Store {
+  // State
+  count: number;
+  items: string[];
+
+  // Actions
+  increment: () => void;
+  decrement: () => void;
+  addItem: (item: string) => void;
+  removeItem: (id: string) => void;
+  reset: () => void;
+}
+
+const initialState = {
+  count: 0,
+  items: [],
+};
+
+export const useStore = create<Store>((set) => ({
+  ...initialState,
+
+  increment: () => set((state) => ({ count: state.count + 1 })),
+
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+
+  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+
+  removeItem: (id) => set((state) => ({
+    items: state.items.filter((item) => item !== id),
+  })),
+
+  reset: () => set(initialState),
+}));
+```
+
+### Using Store in Components
+
+```tsx
+'use client';
+
+import { useStore } from '@/services/store/myStore';
+
+export function Counter() {
+  const count = useStore((state) => state.count);
+  const increment = useStore((state) => state.increment);
+  const decrement = useStore((state) => state.decrement);
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={increment}>+</button>
+      <button onClick={decrement}>-</button>
+    </div>
+  );
+}
+```
+
+---
+
+## Data Fetching with React Query
+
+Use React Query (@tanstack/react-query) for server state management.
+
+### Query Pattern
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+
+export function useDataQuery(id: string) {
+  return useQuery({
+    queryKey: ['data', id],
+    queryFn: () => fetchData(id),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    gcTime: 10 * 60 * 1000, // 10 minutes (formerly cacheTime)
+    enabled: !!id, // Only run if id exists
+  });
+}
+```
+
+### Mutation Pattern
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+
+export function useCreateMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createData,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['data'] });
+      toast.success('Created successfully');
+    },
+    onError: (error: Error) => {
+      toast.error(error.message);
+    },
+  });
+}
+```
+
+### Optimistic Updates
+
+```typescript
+export function useUpdateMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: updateData,
+    onMutate: async (newData) => {
+      // Cancel outgoing queries
+      await queryClient.cancelQueries({ queryKey: ['data', newData.id] });
+
+      // Snapshot previous value
+      const previousData = queryClient.getQueryData(['data', newData.id]);
+
+      // Optimistically update
+      queryClient.setQueryData(['data', newData.id], newData);
+
+      return { previousData };
+    },
+    onError: (err, newData, context) => {
+      // Rollback on error
+      queryClient.setQueryData(['data', newData.id], context?.previousData);
+    },
+    onSettled: (data, error, variables) => {
+      queryClient.invalidateQueries({ queryKey: ['data', variables.id] });
+    },
+  });
+}
+```
+
+---
+
+## Form Patterns
+
+Use react-hook-form with Zod validation.
+
+### Basic Form Pattern
+
+```tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Form } from '@/components/ui/form/Form';
+import { Input } from '@/components/ui/Input';
+import { Button } from '@/components/ui/Button';
+
+const schema = z.object({
+  email: z.string().email('Errors.validation.email'),
+  password: z.string().min(8, 'Errors.validation.minLength|{"min":8}'),
+});
+
+type FormData = z.infer<typeof schema>;
+
+export function LoginForm() {
+  const form = useForm<FormData>({
+    resolver: zodResolver(schema),
+    defaultValues: {
+      email: '',
+      password: '',
+    },
+  });
+
+  const onSubmit = (data: FormData) => {
+    console.log(data);
+  };
+
+  return (
+    <Form form={form} validationSchema={schema}>
+      <Form.Item name="email">
+        {(props) => <Input {...props} label="Email" type="email" />}
+      </Form.Item>
+
+      <Form.Item name="password">
+        {(props) => <PasswordInput {...props} label="Password" />}
+      </Form.Item>
+
+      <Button onPress={form.handleSubmit(onSubmit)} isLoading={form.formState.isSubmitting}>
+        Login
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Form with Mutation
+
+```tsx
+import { useLoginMutation } from '@/services/auth';
+
+export function LoginForm() {
+  const form = useForm<FormData>();
+  const loginMutation = useLoginMutation();
+
+  const onSubmit = (data: FormData) => {
+    loginMutation.mutate(data);
+  };
+
+  return (
+    <Form form={form}>
+      {/* Form fields */}
+      <Button onPress={form.handleSubmit(onSubmit)} isLoading={loginMutation.isPending}>
+        Login
+      </Button>
+    </Form>
+  );
+}
+```
+
+---
+
+## Validation Patterns
+
+### Zod Schema Patterns
+
+```typescript
+import { z } from 'zod';
+
+// Basic validations
+const basicSchema = z.object({
+  email: z.string().email('Errors.validation.email'),
+  password: z.string().min(8, 'Errors.validation.minLength|{"min":8}'),
+  age: z.number().min(18, 'Errors.validation.minAge|{"age":18}'),
+  website: z.string().url('Errors.validation.url').optional(),
+});
+
+// Complex validations
+const complexSchema = z.object({
+  password: z.string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(/[A-Z]/, 'Password must contain uppercase letter')
+    .regex(/[a-z]/, 'Password must contain lowercase letter')
+    .regex(/[0-9]/, 'Password must contain number'),
+
+  confirmPassword: z.string(),
+}).refine((data) => data.password === data.confirmPassword, {
+  message: 'Passwords do not match',
+  path: ['confirmPassword'],
+});
+
+// Array validation
+const arraySchema = z.object({
+  tags: z.array(z.string()).min(1, 'At least one tag required'),
+  items: z.array(z.object({
+    id: z.string(),
+    quantity: z.number().min(1),
+  })),
+});
+
+// Conditional validation
+const conditionalSchema = z.object({
+  type: z.enum(['individual', 'company']),
+  companyName: z.string().optional(),
+}).refine((data) => {
+  if (data.type === 'company') {
+    return !!data.companyName;
+  }
+  return true;
+}, {
+  message: 'Company name is required',
+  path: ['companyName'],
+});
+```
+
+---
+
+## Internationalization (i18n)
+
+Use next-intl for translations.
+
+### Translation Files
+
+**English:** `/src/locales/en.json`
+**German:** `/src/locales/de.json`
+
+```json
+{
+  "Common": {
+    "submit": "Submit",
+    "cancel": "Cancel",
+    "save": "Save"
+  },
+  "Errors": {
+    "validation": {
+      "required": "This field is required",
+      "email": "Invalid email address",
+      "minLength": "Minimum {min} characters required"
+    }
+  }
+}
+```
+
+### Using Translations
+
+```tsx
+'use client';
+
+import { useTranslations } from 'next-intl';
+
+export function MyComponent() {
+  const t = useTranslations('Common');
+
+  return (
+    <div>
+      <h1>{t('title')}</h1>
+      <Button>{t('submit')}</Button>
+    </div>
+  );
+}
+```
+
+### Translation with Parameters
+
+```tsx
+const t = useTranslations('Errors.validation');
+
+// Usage
+t('minLength', { min: 8 }); // "Minimum 8 characters required"
+```
+
+---
+
+## Authentication Patterns
+
+### Auth Hook Pattern
+
+```typescript
+'use client';
+
+import { useMutation } from '@tanstack/react-query';
+import { useRouter } from 'next/navigation';
+import { toast } from 'sonner';
+
+export function useLoginMutation(redirectUrl?: string) {
+  const router = useRouter();
+
+  return useMutation({
+    mutationFn: loginAction,
+    onSuccess: async (result) => {
+      if (result.success) {
+        toast.success('Login successful');
+
+        // Wait for cookies to propagate
+        await new Promise(resolve => setTimeout(resolve, 800));
+
+        // Force reload for clean state
+        window.location.href = redirectUrl || '/dashboard';
+      } else {
+        toast.error(result.error);
+      }
+    },
+    onError: (error: Error) => {
+      toast.error(error.message);
+    },
+  });
+}
+```
+
+---
+
+## API Communication
+
+### API Request Utility
+
+```typescript
+interface ApiRequestOptions {
+  url: string;
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+  data?: unknown;
+  headers?: Record<string, string>;
+}
+
+export async function apiRequest<T>({ url, method, data, headers }: ApiRequestOptions): Promise<T> {
+  const response = await fetch(url, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
+    },
+    ...(data && { body: JSON.stringify(data) }),
+  });
+
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.message || 'API request failed');
+  }
+
+  return response.json();
+}
+```
+
+---
+
+## Summary
+
+Follow these architectural patterns for:
+
+1. **Consistency** - All features use the same structure
+2. **Maintainability** - Easy to find and update code
+3. **Type Safety** - Full TypeScript coverage
+4. **Performance** - Optimized data fetching and caching
+5. **Developer Experience** - Clear patterns and conventions
+
+## Need More Information?
+
+- **Quick Reference** → See `AI_QUICK_REFERENCE.md`
+- **UI Components** → See `UI_COMPONENTS_GUIDE.md`
+- **Implementation Guide** → See `IMPLEMENTATION_GUIDE.md`
+- **Figma to Code** → See `FIGMA_TO_CODE_GUIDE.md`