@adlas/create-app 1.0.0

package/templates/docs/DOCUMENTATION_INDEX.md

@@ -0,0 +1,411 @@
+# Documentation Index
+
+Central hub for all documentation in the Berndorf e-commerce project. Use this index to quickly find the information you need.
+
+## Overview
+
+This documentation suite provides comprehensive guidance for implementing features in the Berndorf e-commerce project. Each document serves a specific purpose and covers different aspects of development.
+
+## Documentation Files
+
+### 1. AI_QUICK_REFERENCE.md
+
+**Purpose:** Quick reference guide for AI and developers
+
+**Use When:**
+- Starting a new feature
+- Need a quick reminder of patterns
+- Looking for code templates
+- Checking DO/DON'T rules
+
+**Contains:**
+- Critical rules (DO/DON'T)
+- Available UI components list
+- Code templates (ready to copy)
+- Styling quick reference
+- Common patterns
+- Implementation workflow
+- Quick checklist
+
+**Best For:**
+- Fast lookups
+- Code snippets
+- Rule verification
+- Daily development
+
+**Link:** [AI_QUICK_REFERENCE.md](./AI_QUICK_REFERENCE.md)
+
+---
+
+### 2. UI_COMPONENTS_GUIDE.md
+
+**Purpose:** Complete reference for all UI components
+
+**Use When:**
+- Building forms
+- Creating layouts
+- Need component props
+- Checking available variants
+- Looking for usage examples
+
+**Contains:**
+- All UI components from `/src/components/ui/`
+- Component props and types
+- Variants and options
+- Usage examples
+- Best practices
+- Element components from `/src/components/elements/`
+- Component patterns
+
+**Best For:**
+- Component selection
+- Props reference
+- Implementation examples
+- Component discovery
+
+**Link:** [UI_COMPONENTS_GUIDE.md](./UI_COMPONENTS_GUIDE.md)
+
+---
+
+### 3. ARCHITECTURE_PATTERNS.md
+
+**Purpose:** Architectural patterns and best practices
+
+**Use When:**
+- Creating a new service module
+- Setting up state management
+- Implementing data fetching
+- Need validation patterns
+- Creating server actions
+
+**Contains:**
+- Service module pattern (complete structure)
+- State management with Zustand
+- Data fetching with React Query
+- Form patterns with react-hook-form
+- Validation patterns with Zod
+- i18n patterns with next-intl
+- Authentication patterns
+- API communication patterns
+- Complete code examples
+
+**Best For:**
+- Feature architecture
+- Pattern reference
+- Code organization
+- Best practices
+
+**Link:** [ARCHITECTURE_PATTERNS.md](./ARCHITECTURE_PATTERNS.md)
+
+---
+
+### 4. IMPLEMENTATION_GUIDE.md
+
+**Purpose:** Step-by-step implementation guide
+
+**Use When:**
+- Implementing a new feature from scratch
+- Need step-by-step instructions
+- Creating service modules
+- Need implementation checklist
+- Troubleshooting issues
+
+**Contains:**
+- Pre-implementation checklist
+- Step-by-step implementation process
+- Service module creation
+- Translation setup
+- Component creation
+- Form implementation
+- Quality checklist
+- Troubleshooting guide
+- Complete example implementation
+
+**Best For:**
+- Feature implementation
+- Step-by-step guidance
+- Checklists
+- Troubleshooting
+
+**Link:** [IMPLEMENTATION_GUIDE.md](./IMPLEMENTATION_GUIDE.md)
+
+---
+
+### 5. FIGMA_TO_CODE_GUIDE.md
+
+**Purpose:** Convert Figma designs to code
+
+**Use When:**
+- Implementing from Figma designs
+- Using Figma MCP Server
+- Mapping design tokens
+- Need component mapping rules
+- Analyzing designs
+
+**Contains:**
+- Figma MCP Server usage
+- Design analysis workflow
+- Design token mapping (colors, spacing, typography)
+- Component mapping rules
+- AI decision tree
+- Figma to code examples
+- Quality checklist
+
+**Best For:**
+- Design implementation
+- Token mapping
+- Component selection from design
+- Design analysis
+
+**Link:** [FIGMA_TO_CODE_GUIDE.md](./FIGMA_TO_CODE_GUIDE.md)
+
+---
+
+## Usage Scenarios
+
+### Scenario 1: Starting a New Feature
+
+**Workflow:**
+
+1. **Read:** `IMPLEMENTATION_GUIDE.md` - Pre-implementation checklist
+2. **Refer to:** `ARCHITECTURE_PATTERNS.md` - Service module structure
+3. **Use:** `AI_QUICK_REFERENCE.md` - Code templates
+4. **Check:** `UI_COMPONENTS_GUIDE.md` - Available components
+5. **Follow:** `IMPLEMENTATION_GUIDE.md` - Step-by-step process
+
+### Scenario 2: Implementing from Figma
+
+**Workflow:**
+
+1. **Read:** `FIGMA_TO_CODE_GUIDE.md` - Design analysis workflow
+2. **Use:** Figma MCP Server - Analyze design
+3. **Map:** Design tokens to project tokens
+4. **Check:** `UI_COMPONENTS_GUIDE.md` - Component mapping
+5. **Refer to:** `AI_QUICK_REFERENCE.md` - Code templates
+6. **Implement:** Following patterns from `ARCHITECTURE_PATTERNS.md`
+
+### Scenario 3: Creating a Form
+
+**Workflow:**
+
+1. **Check:** `UI_COMPONENTS_GUIDE.md` - Form components
+2. **Refer to:** `ARCHITECTURE_PATTERNS.md` - Form patterns
+3. **Use:** `AI_QUICK_REFERENCE.md` - Form template
+4. **Follow:** `IMPLEMENTATION_GUIDE.md` - Quality checklist
+
+### Scenario 4: Debugging an Issue
+
+**Workflow:**
+
+1. **Check:** `IMPLEMENTATION_GUIDE.md` - Troubleshooting section
+2. **Verify:** `AI_QUICK_REFERENCE.md` - Rules and patterns
+3. **Review:** `ARCHITECTURE_PATTERNS.md` - Correct patterns
+4. **Test:** Against examples in respective guides
+
+### Scenario 5: Quick Component Lookup
+
+**Workflow:**
+
+1. **Check:** `AI_QUICK_REFERENCE.md` - Available components
+2. **Details:** `UI_COMPONENTS_GUIDE.md` - Component props and examples
+3. **Implement:** Using code from guides
+
+---
+
+## Quick Links by Topic
+
+### Components
+
+- **List of components:** [AI_QUICK_REFERENCE.md](./AI_QUICK_REFERENCE.md#available-ui-components)
+- **Detailed component guide:** [UI_COMPONENTS_GUIDE.md](./UI_COMPONENTS_GUIDE.md)
+- **Component patterns:** [UI_COMPONENTS_GUIDE.md](./UI_COMPONENTS_GUIDE.md#component-usage-patterns)
+
+### Forms
+
+- **Form components:** [UI_COMPONENTS_GUIDE.md](./UI_COMPONENTS_GUIDE.md#form-components)
+- **Form patterns:** [ARCHITECTURE_PATTERNS.md](./ARCHITECTURE_PATTERNS.md#form-patterns)
+- **Form template:** [AI_QUICK_REFERENCE.md](./AI_QUICK_REFERENCE.md#5-form-with-validation)
+- **Form implementation:** [IMPLEMENTATION_GUIDE.md](./IMPLEMENTATION_GUIDE.md#step-11-create-form-components)
+
+### State Management
+
+- **Zustand patterns:** [ARCHITECTURE_PATTERNS.md](./ARCHITECTURE_PATTERNS.md#state-management-with-zustand)
+- **Store template:** [AI_QUICK_REFERENCE.md](./AI_QUICK_REFERENCE.md#4-zustand-store)
+- **Store creation:** [IMPLEMENTATION_GUIDE.md](./IMPLEMENTATION_GUIDE.md#step-7-create-zustand-store-if-needed)
+
+### Data Fetching
+
+- **React Query patterns:** [ARCHITECTURE_PATTERNS.md](./ARCHITECTURE_PATTERNS.md#data-fetching-with-react-query)
+- **Query template:** [AI_QUICK_REFERENCE.md](./AI_QUICK_REFERENCE.md#3-react-query-hook)
+- **Query implementation:** [IMPLEMENTATION_GUIDE.md](./IMPLEMENTATION_GUIDE.md#step-5-create-react-query-hooks)
+
+### Validation
+
+- **Validation patterns:** [ARCHITECTURE_PATTERNS.md](./ARCHITECTURE_PATTERNS.md#validation-patterns)
+- **Zod schemas:** [ARCHITECTURE_PATTERNS.md](./ARCHITECTURE_PATTERNS.md#zod-schema-patterns)
+
+### Styling
+
+- **Styling reference:** [AI_QUICK_REFERENCE.md](./AI_QUICK_REFERENCE.md#styling-quick-reference)
+- **Design tokens:** [FIGMA_TO_CODE_GUIDE.md](./FIGMA_TO_CODE_GUIDE.md#design-token-mapping)
+- **Color mapping:** [FIGMA_TO_CODE_GUIDE.md](./FIGMA_TO_CODE_GUIDE.md#color-mapping)
+- **Spacing mapping:** [FIGMA_TO_CODE_GUIDE.md](./FIGMA_TO_CODE_GUIDE.md#spacing-mapping)
+
+### Translations
+
+- **i18n patterns:** [ARCHITECTURE_PATTERNS.md](./ARCHITECTURE_PATTERNS.md#internationalization-i18n)
+- **Translation usage:** [AI_QUICK_REFERENCE.md](./AI_QUICK_REFERENCE.md#7-translation-usage)
+- **Translation setup:** [IMPLEMENTATION_GUIDE.md](./IMPLEMENTATION_GUIDE.md#step-9-add-translations)
+
+### Service Modules
+
+- **Service pattern:** [ARCHITECTURE_PATTERNS.md](./ARCHITECTURE_PATTERNS.md#service-module-pattern)
+- **Complete example:** [ARCHITECTURE_PATTERNS.md](./ARCHITECTURE_PATTERNS.md#complete-example-product-service-module)
+- **Implementation steps:** [IMPLEMENTATION_GUIDE.md](./IMPLEMENTATION_GUIDE.md#step-1-create-service-module-structure)
+
+### Figma to Code
+
+- **Figma MCP usage:** [FIGMA_TO_CODE_GUIDE.md](./FIGMA_TO_CODE_GUIDE.md#figma-mcp-server-usage)
+- **Design analysis:** [FIGMA_TO_CODE_GUIDE.md](./FIGMA_TO_CODE_GUIDE.md#design-analysis-workflow)
+- **Component mapping:** [FIGMA_TO_CODE_GUIDE.md](./FIGMA_TO_CODE_GUIDE.md#component-mapping-rules)
+- **Examples:** [FIGMA_TO_CODE_GUIDE.md](./FIGMA_TO_CODE_GUIDE.md#examples)
+
+---
+
+## Visual Guide
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    DOCUMENTATION SUITE                       │
+└─────────────────────────────────────────────────────────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        │                   │                   │
+        ▼                   ▼                   ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│  Quick Start  │   │  Components   │   │ Architecture  │
+│               │   │               │   │               │
+│ AI_QUICK_     │   │ UI_COMPONENTS_│   │ ARCHITECTURE_ │
+│ REFERENCE.md  │   │ GUIDE.md      │   │ PATTERNS.md   │
+│               │   │               │   │               │
+│ • Rules       │   │ • All UI      │   │ • Service     │
+│ • Templates   │   │   components  │   │   modules     │
+│ • Patterns    │   │ • Props       │   │ • State mgmt  │
+│ • Checklists  │   │ • Examples    │   │ • Data fetch  │
+└───────────────┘   └───────────────┘   └───────────────┘
+        │                   │                   │
+        └───────────────────┼───────────────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        │                   │                   │
+        ▼                   ▼                   ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│Implementation │   │  Figma to     │   │Documentation  │
+│               │   │  Code         │   │   Index       │
+│ IMPLEMENTATION│   │               │   │               │
+│ _GUIDE.md     │   │ FIGMA_TO_     │   │ DOCUMENTATION_│
+│               │   │ CODE_GUIDE.md │   │ INDEX.md      │
+│ • Steps       │   │               │   │               │
+│ • Checklists  │   │ • MCP Server  │   │ • Overview    │
+│ • Trouble-    │   │ • Token map   │   │ • Scenarios   │
+│   shooting    │   │ • Examples    │   │ • Quick links │
+└───────────────┘   └───────────────┘   └───────────────┘
+```
+
+---
+
+## Documentation Maintenance
+
+### Updating Documentation
+
+When updating any documentation file:
+
+1. **Update the file** with new information
+2. **Update this index** if structure changes
+3. **Update cross-references** in related files
+4. **Test examples** to ensure they work
+5. **Update version** or date if applicable
+
+### Adding New Documentation
+
+When adding a new documentation file:
+
+1. **Create the file** with clear structure
+2. **Add entry to this index** with description
+3. **Add cross-references** from related files
+4. **Update visual guide** if needed
+5. **Update usage scenarios** if applicable
+
+---
+
+## Best Practices
+
+### For AI Assistants
+
+1. **Start with Quick Reference** for fast lookups
+2. **Deep dive into specific guides** for detailed information
+3. **Follow implementation steps** from Implementation Guide
+4. **Use examples** as templates, not just reference
+5. **Cross-reference** between documents for complete understanding
+
+### For Developers
+
+1. **Bookmark this index** for quick access
+2. **Use search** (Cmd/Ctrl + F) within documents
+3. **Follow checklists** to ensure quality
+4. **Refer to examples** when in doubt
+5. **Keep documentation open** while implementing
+
+### For Teams
+
+1. **Share this index** with new team members
+2. **Update documentation** as patterns evolve
+3. **Contribute examples** from real implementations
+4. **Report issues** in documentation
+5. **Suggest improvements** based on usage
+
+---
+
+## Summary
+
+This documentation suite covers:
+
+1. **Quick Reference** - Fast lookups and templates
+2. **UI Components** - All available components
+3. **Architecture** - Patterns and best practices
+4. **Implementation** - Step-by-step guides
+5. **Figma to Code** - Design implementation
+6. **This Index** - Navigation and overview
+
+Use this index as your starting point for any development task in the Berndorf e-commerce project.
+
+---
+
+## Need Help?
+
+If you can't find what you're looking for:
+
+1. **Check this index** - Use Quick Links section
+2. **Search within files** - Use Cmd/Ctrl + F
+3. **Check related sections** - Cross-references
+4. **Review examples** - Often contain what you need
+5. **Check troubleshooting** - In Implementation Guide
+
+---
+
+## Version Information
+
+**Documentation Suite Version:** 1.0
+**Last Updated:** 2025-11-27
+**Project:** Berndorf E-commerce (Next.js 15, HeroUI, TypeScript)
+**Tech Stack:**
+- Next.js 15.5.4
+- React 19.2.0
+- HeroUI 2.8.5
+- TypeScript 5.9.3
+- Tailwind CSS 4.1.17
+- Zustand 5.0.8
+- React Query 5.90.7
+- react-hook-form 7.66.0
+- Zod 4.1.12
+- next-intl 4.5.0