marketplaces/README.md

# Dexar Market (Multi-Brand Marketplace)

A modern, responsive marketplace application built with Angular 20 that supports multiple brands from a single codebase.

## 🎨 Multi-Brand Support

This project supports **two brands** with the same codebase:
- **Dexar Market** - Purple theme (`http://localhost:4200`)
- **Novo Market** - Green theme (`http://localhost:4201`)

Each brand has its own:
- Colors and themes
- Logos and branding
- Environment configuration
- Production builds

## Features

- 🎨 **Multi-Brand Architecture** - Single codebase, multiple brands
- 📱 **Fully Responsive** - Optimized for desktop, tablet, and mobile devices
- 🏪 **Category Browsing** - Hierarchical category navigation
- ♾️ **Infinite Scroll** - Seamless product loading in categories and search
- 🔍 **Real-time Search** - Debounced search with live results
- 🛒 **Shopping Cart** - API-managed cart with quantity support
- 📞 **Phone Collection** - Russian phone number formatting and validation
- ⭐ **Product Reviews** - Display ratings, reviews, and Q&A
- 💳 **Payment Integration** - Telegram Web App payment flow
- 📧 **Email Notifications** - Purchase confirmation emails
- 📱 **PWA Support** - Progressive Web App with offline support
- 🔔 **Service Worker** - Smart caching for better performance
- 🎨 **Modern UI** - Clean, intuitive interface with smooth animations

## Tech Stack

- **Angular 21** - Latest Angular with standalone components and signals
- **TypeScript** - Type-safe development
- **SCSS** - Modular styling with theme-based architecture
- **RxJS** - Reactive programming for API calls
- **Signals** - Angular signals for reactive state management
- **Telegram Web App** - Integration with Telegram Mini Apps
- **PWA** - Service workers and offline support

## Quick Start

### Development

**Run Dexar Market (Purple):**
```bash
npm start
# or
npm run start:dexar
```
Open: http://localhost:4200

**Run Novo Market (Green):**
```bash
npm run start:novo
```
Open: http://localhost:4201

### Production Build

**Build Dexar Market:**
```bash
npm run build:dexar
```
Output: `dist/dexarmarket/`

**Build Novo Market:**
```bash
npm run build:novo
```
Output: `dist/novomarket/`

## Project Structure

```
src/
├── app/
│   ├── components/
│   │   ├── header/           # Brand-aware header
│   │   ├── footer/           # Brand-aware footer
│   │   └── logo/             # Dynamic logo component
│   ├── models/
│   │   ├── category.model.ts # Category interface
│   │   └── item.model.ts     # Item, Photo, Callback, Question
│   ├── pages/
│   │   ├── home/             # Categories overview
│   │   ├── category/         # Product listing with infinite scroll
│   │   ├── item-detail/      # Product details
│   │   ├── search/           # Search with infinite scroll
│   │   ├── cart/             # Shopping cart with checkout
│   │   ├── info/             # About, contacts, FAQ, etc.
│   │   └── legal/            # Legal documents
│   ├── services/
│   │   ├── api.service.ts    # HTTP API integration
│   │   ├── cart.service.ts   # Cart state management (signals)
│   │   └── telegram.service.ts # Telegram WebApp integration
│   └── interceptors/
│       └── cache.interceptor.ts # API caching
├── environments/
│   ├── environment.ts                    # Dexar development
│   ├── environment.production.ts         # Dexar production
│   ├── environment.novo.ts               # Novo development
│   └── environment.novo.production.ts    # Novo production
├── styles/
│   ├── themes/
│   │   ├── dexar.theme.scss # Purple theme
│   │   └── novo.theme.scss  # Green theme
│   └── shared-legal.scss    # Shared legal page styles
├── index.html               # Dexar HTML
└── index.novo.html         # Novo HTML
```

## API Endpoints

**Base URL:** Configured per environment

### Health Check
- `GET /ping` - Server availability check

### Categories
- `GET /category` - Get all categories (hierarchical)

### Items
- `GET /category/:categoryID?count=50&skip=100` - Get items in category (paginated)
- `GET /items?search=query&count=50&skip=100` - Search items (paginated)

### Cart
- `GET /cart` - Get cart items with quantities
- `POST /cart` - Add item `{ itemID: number, quantity?: number }`
- `PATCH /cart` - Update quantity `{ itemID: number, quantity: number }`
- `DELETE /cart` - Remove items `[itemID1, itemID2, ...]`

### Payment
- `POST /payment/create` - Create payment intent
- `POST /purchase-email` - Send purchase confirmation

See [docs/API_CHANGES_REQUIRED.md](docs/API_CHANGES_REQUIRED.md) for detailed API specifications.

## Environment Configuration

Each brand has development and production environments:

### Dexar Market
**Development** (`environment.ts`):
```typescript
{
  production: false,
  brandName: 'Dexar Market',
  apiUrl: '/api',  // Uses proxy
  // ... other config
}
```

**Production** (`environment.production.ts`):
```typescript
{
  production: true,
  brandName: 'Dexar Market',
  apiUrl: 'https://api.dexarmarket.ru',
  // ... other config
}
```

### Novo Market
**Development** (`environment.novo.ts`):
```typescript
{
  production: false,
  brandName: 'novo Market',
  apiUrl: '/api',  // Uses proxy
  // ... other config
}
```

**Production** (`environment.novo.production.ts`):
```typescript
{
  production: true,
  brandName: 'novo Market',
  apiUrl: 'https://api.novomarket.ru',  // To be configured
  // ... other config
}
```

## Deployment

### Prerequisites
1. Node.js 18+ and npm installed
2. Backend API running and accessible
3. Domain names configured (dexarmarket.ru, novomarket.ru)

### Build for Production

**For Dexar Market:**
```bash
npm run build:dexar
```
Output: `dist/dexarmarket/`

**For Novo Market:**
```bash
npm run build:novo
```
Output: `dist/novomarket/`

### Nginx Configuration

When deploying to production, you **must** configure nginx to handle Angular routing properly.

**Example nginx config (Dexar):**
```nginx
server {
    listen 80;
    server_name dexarmarket.ru www.dexarmarket.ru;
    
    root /var/www/dexarmarket;
    index index.html;
    
    # Angular routing support
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # Gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
    
    # Cache static assets
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

**For Novo Market**, use the same config with `novomarket.ru` and `/var/www/novomarket`.

### SSL Setup

Enable HTTPS with Let's Encrypt:
```bash
sudo certbot --nginx -d dexarmarket.ru -d www.dexarmarket.ru
sudo certbot --nginx -d novomarket.ru -d www.novomarket.ru
```

### Deploy Steps

1. Build the project:
   ```bash
   npm run build:dexar
   npm run build:novo
   ```

2. Upload to server:
   ```bash
   scp -r dist/dexarmarket/* user@server:/var/www/dexarmarket/
   scp -r dist/novomarket/* user@server:/var/www/novomarket/
   ```

3. Configure nginx (see above)

4. Reload nginx:
   ```bash
   sudo nginx -t
   sudo systemctl reload nginx
   ```

### Important Notes

- The `try_files $uri $uri/ /index.html;` directive is **critical** for Angular routing
- Without it, direct URL access or page refreshes will cause 404 errors
- Each brand needs its own server block with separate domain
- Update API URLs in production environment files before building

## PWA (Progressive Web App)

The application includes PWA support with:
- Service worker for offline caching
- Install prompts on mobile devices
- Brand-specific app icons and manifests
- Background sync capabilities

**Manifests:**
- Dexar: `public/manifest.webmanifest`
- Novo: `public/manifest.novo.webmanifest`

**Configuration:** `ngsw-config.json`

## Development

### Angular CLI Commands

**Generate a new component:**
```bash
ng generate component component-name
```

**For a complete list of schematics:**
```bash
ng generate --help
```

### Running Tests

**Unit tests:**
```bash
ng test
```

**E2E tests:**
```bash
ng e2e
```

## Documentation

Comprehensive documentation is available in the `docs/` folder:

- **[MULTI_BRAND.md](docs/MULTI_BRAND.md)** - Multi-brand architecture guide
- **[QUICK_START_NOVO.md](docs/QUICK_START_NOVO.md)** - Quick start for Novo brand
- **[API_CHANGES_REQUIRED.md](docs/API_CHANGES_REQUIRED.md)** - Backend API requirements
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Deployment instructions
- **[PWA_SETUP.md](docs/PWA_SETUP.md)** - PWA configuration guide
- **[IMPLEMENTATION.md](docs/IMPLEMENTATION.md)** - Implementation details
- **[RECOMMENDATIONS.md](docs/RECOMMENDATIONS.md)** - Roadmap and improvements
- **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues and solutions

## Telegram Integration

The marketplace is designed to work as a Telegram Mini App:

1. Cart data is stored on backend per Telegram user
2. Payment flow uses Telegram's payment system
3. Deep linking support for sharing products
4. Telegram user info auto-collection

## Browser Compatibility

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Mobile browsers (iOS Safari, Chrome Mobile)

## Known Issues & Limitations

1. **Cart quantity support** - Backend needs to implement quantity fields (see [API_CHANGES_REQUIRED.md](docs/API_CHANGES_REQUIRED.md))
2. **Novo brand assets** - Logo and custom images need to be added
3. **Legal documents** - Need real company details for Novo brand before deployment

## Contributing

When contributing, please:
1. Follow the existing code style (use Prettier)
2. Write unit tests for new features
3. Update documentation as needed
4. Test both Dexar and Novo brands before committing

## License

Proprietary - All rights reserved

## Support

For technical support or questions:
- Email: dev@dexarmarket.ru
- Telegram: @dexarmarket

## Additional Resources

- [Angular CLI Documentation](https://angular.dev/tools/cli)
- [Angular Docs](https://angular.dev)
- [Telegram Web Apps](https://core.telegram.org/bots/webapps)