ruch/example/README.md

Revolutionary React TypeScript CLI with hexagonal architecture & AI-powered development assistance. Create maintainable, scalable applications with domain-driven design and integrated AI tooling.

# 🛒 E-Commerce Application - Built with Ruch CLI

> **A complete e-commerce application demonstrating Hexagonal Architecture with React TypeScript**

This is a comprehensive e-commerce application built using **Ruch CLI**, showcasing how to structure a modern React application following hexagonal architecture principles.

## 🏗️ **Architecture Overview**

This application implements **Simplified Hexagonal Architecture** with the following domains:

### 📦 **Core Domains**

- **`user`** - User management, authentication, profiles
- **`product`** - Product catalog, categories, inventory
- **`cart`** - Shopping cart functionality
- **`order`** - Order processing and management
- **`payment`** - Payment processing and methods
- **`notification`** - Email, SMS, push notifications

Each domain follows the hexagonal architecture pattern:

```
src/domains/{domain}/
├── entities/     # Business models & types
├── ports/        # Interfaces (contracts)
├── services/     # Business logic
├── adapters/     # External integrations (API, DB)
├── hooks/        # React Query hooks
└── ui/           # Domain-specific components
```

## 🚀 **Generated with Ruch CLI**

This entire application was created using Ruch CLI commands:

### **Domain Creation**

```bash
# Created all 6 domains using Ruch CLI
npx ruch create user
npx ruch create product
npx ruch create cart
npx ruch create order
npx ruch create payment
npx ruch create notification
```

### **Service Context Generation**

```bash
# Generated dependency injection context
npx ruch context generate
```

### **MSW Setup for Testing**

```bash
# Initialized Mock Service Worker
npx ruch msw init
npx ruch msw handlers
npx ruch msw mocks
```

### **HTTP Client Generation**

```bash
# Generated HTTP client configuration
npx ruch http-client
```

### **AI Documentation**

```bash
# Generated comprehensive AI assistant guides
npx ruch guide-ai
```

## 🎯 **Key Features**

### **🏪 Frontend Features**

- **Homepage** with hero section and featured products
- **Product Catalog** with search, filtering, and sorting
- **Product Cards** with images, specs, and pricing
- **Shopping Cart** functionality (Add to Cart buttons)
- **Responsive Design** with Tailwind CSS
- **Modern UI/UX** with smooth animations

### **🔧 Technical Features**

- **TypeScript** throughout the entire application
- **Hexagonal Architecture** with proper domain separation
- **Mock Data** with realistic e-commerce entities
- **React Hooks** for state management
- **MSW Integration** for API mocking
- **Service Context** for dependency injection
- **AI-Generated Documentation** for each domain

## 📱 **Pages & Routes**

- **`/`** - Homepage with featured products and categories
- **`/products`** - Product listing with search and filters
- **`/products/:id`** - Product detail page
- **`/cart`** - Shopping cart management
- **`/checkout`** - Checkout process
- **`/orders`** - Order history
- **`/profile`** - User profile management
- **`/login`** - User authentication
- **`/admin`** - Admin dashboard

## 🗂️ **Domain Entities**

### **User Domain**

```typescript
interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  role: 'customer' | 'admin' | 'vendor';
  profile?: UserProfile;
}
```

### **Product Domain**

```typescript
interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  currency: 'USD' | 'EUR' | 'GBP';
  category: ProductCategory;
  images: ProductImage[];
  inventory: ProductInventory;
  specifications: ProductSpecification[];
}
```

### **Cart Domain**

```typescript
interface Cart {
  id: string;
  userId: string;
  items: CartItem[];
  totals: CartTotals;
}
```

### **Order Domain**

```typescript
interface Order {
  id: string;
  orderNumber: string;
  userId: string;
  status: OrderStatus;
  items: OrderItem[];
  shippingAddress: Address;
  paymentMethod: PaymentMethod;
}
```

## 🧪 **Testing Strategy**

The application includes comprehensive testing setup:

- **MSW Handlers** for each domain
- **Mock Data Generation** for realistic testing
- **Domain-specific Tests** with proper isolation
- **Service Mocking** following hexagonal principles

## 🔄 **Development Workflow**

### **Adding New Features**

1. **Create Domain**: `npx ruch create {domain-name}`
2. **Update Context**: `npx ruch context generate`
3. **Generate Tests**: `npx ruch msw handlers` + `npx ruch msw mocks`
4. **Update Documentation**: `npx ruch guide-ai`

### **Cross-Domain Communication**

- Use **ports/adapters** for domain communication
- Never import services directly between domains
- Always go through **service context** for dependency injection

## 📚 **Documentation**

The application includes auto-generated documentation:

- **`GUIDE.md`** - Global development guide
- **`ruch-guide.json`** - Machine-readable configuration
- **Domain Guides** - Specific guides for each domain in `src/domains/{domain}/GUIDE.md`

## 🛠️ **Tech Stack**

- **React 18** with TypeScript
- **React Router** for navigation
- **Tailwind CSS** for styling
- **Bun** for package management (following cursor rules)
- **MSW** for API mocking
- **Ruch CLI** for architecture generation

## 🎨 **UI Components**

### **Reusable Components**

- **ProductCard** - Displays product information
- **SearchFilter** - Product search and filtering
- **CategoryGrid** - Category browsing
- **Newsletter** - Email subscription

### **Design System**

- **Consistent Colors** - Blue primary, gray neutrals
- **Typography** - Clear hierarchy with proper sizing
- **Spacing** - Consistent padding and margins
- **Responsive** - Mobile-first design approach

## 🔍 **Mock Data**

The application includes realistic mock data for demonstration:

- **4 Featured Products** with complete specifications
- **Multiple Categories** (Electronics, Fashion, Home & Garden)
- **Realistic Pricing** in USD currency
- **High-Quality Images** from Unsplash
- **Inventory Management** with stock levels

## ⚡ **Performance Optimizations**

- **Lazy Loading** for product images
- **Efficient State Management** with React hooks
- **Optimized Bundle** with proper code splitting
- **Caching Strategy** ready for React Query integration

## 🎯 **Next Steps**

To extend this application:

1. **Connect Real APIs** - Replace mock data with actual backend
2. **Add Authentication** - Implement user login/registration
3. **Payment Integration** - Connect with Stripe/PayPal
4. **Real-time Features** - Add WebSocket for live updates
5. **Advanced Features** - Wishlist, reviews, recommendations

## 🤝 **Contributing**

This application serves as a **reference implementation** for:

- **Hexagonal Architecture** in React
- **Domain-Driven Design** principles
- **Ruch CLI** best practices
- **TypeScript** patterns
- **Modern React** development

---

**Built with ❤️ using [Ruch CLI](https://github.com/your-repo/ruch) - The Revolutionary React Architecture Tool**