# Emporio Sport - Complete System Documentation

## 📖 Table of Contents

1. [Overview](#overview)
2. [Quick Start](#quick-start)
3. [Architecture](#architecture)
4. [File Structure](#file-structure)
5. [Key Components](#key-components)
6. [Configuration](#configuration)
7. [Data Files](#data-files)
8. [Deployment](#deployment)
9. [Troubleshooting](#troubleshooting)

---

## Overview

**Emporio Sport** is a fully responsive e-commerce website with:

- ✅ **Mobile-First Responsive Design** - Optimized for all devices (320px to 4K)
- ✅ **Product Shop** - Dynamic product display with filters, pagination, and ratings
- ✅ **Blog System** - Blog management with categories and tags
- ✅ **Admin Panel** - Manage products, blogs, settings, and more
- ✅ **JSON-Based Content** - No database required for basic functionality
- ✅ **Optional Database** - MySQL integration for dynamic features
- ✅ **Navigation System** - Featured pages + dropdown menus
- ✅ **Image Optimization** - Automatic path detection for localhost and cPanel
- ✅ **SEO Optimized** - Meta tags, structured data, canonical URLs
- ✅ **Multi-Language Support** - English, Italian, Spanish, German

---

## Quick Start

### For Local Development (XAMPP)

1. **Place folder in htdocs:**
   ```
   C:\xampp\htdocs\emporio-sport\
   ```

2. **Access via browser:**
   ```
   http://localhost/emporio-sport/
   ```

3. **Test shop:**
   ```
   http://localhost/emporio-sport/shop.php
   ```

4. **Test validation:**
   ```
   http://localhost/emporio-sport/validate_deployment.php
   ```

### For Production (cPanel)

1. **Upload to public_html:**
   - Via FTP or cPanel File Manager
   - Folder: `emporio-sport` (or any name)

2. **Verify installation:**
   - Visit: `yourdomain.com/validate_deployment.php`
   - All checks should pass

3. **Test features:**
   - Homepage: `yourdomain.com/`
   - Shop: `yourdomain.com/shop.php`
   - Admin: `yourdomain.com/admin_login.php`

4. **Delete validation script:**
   - Remove `validate_deployment.php` after testing

---

## Architecture

### Technology Stack

| Component | Technology |
|-----------|-----------|
| Frontend | HTML5, CSS3, JavaScript (ES6+) |
| Backend | PHP 7.4+ |
| Data | JSON files (or MySQL database) |
| Styling | Custom CSS + Responsive Grid |
| Session | PHP Sessions |
| Images | JPG, PNG, WEBP support |

### Data Flow

```
User Browser
    ↓
HTTP Request
    ↓
PHP (index.php/shop.php/etc)
    ↓
├─ Try Database (if configured)
├─ Fall back to JSON files (/data/*.json)
├─ Load images via path normalization
├─ Process filters/pagination
└─ Return HTML to browser
```

### Path Detection

The system automatically detects whether it's running on:

**Localhost:**
- Base path: `/emporio-sport/`
- URLs: `http://localhost/emporio-sport/shop.php`

**cPanel:**
- Base path: `/`
- URLs: `https://yourdomain.com/shop.php`

This is handled automatically by `getWebBasePath()` in `/config/image_config.php`

---

## File Structure

```
emporio-sport/
├── index.php                          # Homepage
├── shop.php                           # Product shop page
├── product.php                        # Product detail page
├── cart.php                           # Shopping cart
├── checkout.php                       # Checkout page
├── contact.php                        # Contact form
├── about.php                          # About page
├── blogs.php                          # Blog listing
├── blog.php                           # Blog detail page
├── admin_login.php                    # Admin login
├── admin_dashboard.php                # Admin dashboard
├── admin_products.php                 # Manage products
├── admin_blogs.php                    # Manage blogs
├── admin_*.php                        # Other admin pages
├── .htaccess                          # URL rewriting + security
├── header.php                         # Site header (included in all pages)
├── footer.php                         # Site footer (included in all pages)
│
├── css/
│   ├── styles.css                     # Main stylesheet
│   ├── responsive-system.css          # Responsive design (5+ breakpoints)
│   ├── navigation-menu.css            # Navigation menu + dropdown
│   ├── layout-system.css              # Layout grid system
│   └── ... (other CSS files)
│
├── js/
│   ├── main.js                        # Main JavaScript
│   ├── shop.js                        # Shop functionality
│   ├── cart.js                        # Cart operations
│   └── ... (other JS files)
│
├── config/
│   ├── db_config.php                  # Database configuration
│   ├── image_config.php               # Image path normalization
│   └── translation_helper.php         # Multi-language support
│
├── helpers/
│   ├── navigation_helper.php          # Pages menu + featured pages
│   ├── meta_tags_helper.php           # SEO meta tags
│   ├── schema_helper.php              # Structured data (JSON-LD)
│   └── ... (other helper files)
│
├── classes/
│   ├── ImageHandler.php               # Image processing
│   ├── DatabaseHelper.php             # Database operations
│   └── ... (other classes)
│
├── data/
│   ├── products.json                  # All products (19+ items)
│   ├── categories.json                # Product categories (12+)
│   ├── pages.json                     # Website pages (for navigation)
│   ├── brands.json                    # Product brands (optional)
│   ├── site_config.json               # Site settings
│   ├── footer_config.json             # Footer content
│   └── ... (other JSON files)
│
├── pics_ecom/
│   ├── tennis.jpg                     # Product images
│   ├── placeholder.png                # Fallback image
│   └── ... (more product images)
│
├── sport-pics/
│   ├── logo-1.png                     # Site logo
│   ├── soccer/
│   │   ├── calcio.jpg
│   │   └── ... (soccer images)
│   ├── tennis/
│   │   └── ... (tennis images)
│   ├── rugby/
│   │   └── ... (rugby images)
│   └── ... (more sport categories)
│
├── uploads/
│   └── (temporary uploaded files)
│
└── validate_deployment.php            # Deployment validation script

```

---

## Key Components

### 1. Navigation System

**Files:**
- `/helpers/navigation_helper.php` (300 lines)
- `/css/navigation-menu.css` (753 lines)
- `/header.php` (450+ lines)

**Features:**
- Featured pages (up to 4) displayed in header
- Non-featured pages in dropdown menu
- Database + JSON fallback
- Hover-activated dropdown
- Mobile responsive

**How it works:**
```php
// Get featured pages (from DB or JSON fallback)
$featuredPages = NavigationHelper::getFeaturedPages();

// Get all pages (for dropdown)
$allPages = NavigationHelper::getAllPages();

// Render in header.php
foreach ($featuredPages as $page) {
    echo '<a href="' . $page['url'] . '">' . $page['title'] . '</a>';
}
```

### 2. Product Shop

**Files:**
- `/shop.php` (1,673 lines)
- `/product.php` (product detail)
- `/data/products.json` (19+ products)

**Features:**
- Dynamic product display from JSON
- 6 filter types: Category, Price, Rating, Brand
- Pagination with adjustable per-page count
- Responsive grid layout
- Product search
- Image lazy loading

**Data Structure:**
```json
{
    "id": 1,
    "title": "Tennis Racket",
    "price": 40.00,
    "cat": "Tennis",
    "image": "tennis.jpg",
    "rating": 4.5,
    "sale_price": 30.00,
    "on_sale": true
}
```

### 3. Image System

**Files:**
- `/config/image_config.php` (228 lines)
- `/classes/ImageHandler.php`

**Features:**
- Automatic base path detection (localhost vs cPanel)
- Image path normalization
- Supports multiple image locations:
  - `/pics_ecom/` (product images)
  - `/sport-pics/` (category/feature images)
  - `/uploads/` (user uploads)
- Fallback to placeholder image

**Usage:**
```php
// Auto-detects correct path based on environment
$imagePath = getImageForSection('tennis.jpg');
// Localhost: /emporio-sport/pics_ecom/tennis.jpg
// cPanel: /pics_ecom/tennis.jpg
```

### 4. Responsive Design

**Files:**
- `/css/responsive-system.css` (850+ lines)
- Responsive rules in other CSS files

**Breakpoints:**
```css
/* Extra small devices (< 480px) */
@media (max-width: 479px) { }

/* Small devices: Tablets (480px - 767px) */
@media (max-width: 767px) { }

/* Medium devices: Tablets landscape (768px - 1023px) */
@media (max-width: 1023px) { }

/* Large devices: Desktops (1024px - 1199px) */
@media (min-width: 1024px) { }

/* Extra large devices: Large screens (1200px+) */
@media (min-width: 1200px) { }
```

**Features:**
- Mobile-first approach
- Touch-optimized (44px minimum tap targets)
- Landscape orientation handling
- Font scaling for readability
- Accessibility (dark mode, high contrast support)

### 5. Admin Panel

**Files:**
- `/admin_login.php` - Login page
- `/admin_dashboard.php` - Main dashboard
- `/admin_products.php` - Product management
- `/admin_blogs.php` - Blog management
- `/admin_*.php` - Other admin pages

**Features:**
- Secure admin login
- Product add/edit/delete
- Blog management
- Site settings
- Image upload
- Database backup

---

## Configuration

### Database (Optional)

Edit `/config/db_config.php`:

```php
$host = 'localhost';           // Server (usually 'localhost')
$db_name = 'emporio_sport';    // Database name
$user = 'root';                // Database user
$password = '';                // Database password
```

**Note:** The system works WITHOUT database if JSON files are present.

### Site Settings

Edit `/data/site_config.json`:

```json
{
    "title": "Emporio Sport",
    "logo": "sport-pics/logo-1.png",
    "tagline": "Professional Sports Equipment",
    "email": "info@emporio-sport.com",
    "phone": "+1 (555) 123-4567",
    "header_bg_color": "#ffffff"
}
```

### Image Paths

Images are stored in multiple locations:

| Location | Purpose | Path in JSON |
|----------|---------|----------|
| `/pics_ecom/` | Product images | `"tennis.jpg"` or `"pics_ecom/tennis.jpg"` |
| `/sport-pics/` | Category/feature images | `"sport-pics/soccer/calcio.jpg"` |
| `/uploads/` | User uploaded images | Auto-generated path |

---

## Data Files

All data stored in JSON files in `/data/` directory:

### products.json
```json
[
    {
        "id": 1,
        "title": "Product Name",
        "price": 29.99,
        "cat": "Category Name",
        "image": "image-file.jpg",
        "rating": 4.5,
        "sale_price": 19.99,
        "on_sale": true
    }
]
```

### categories.json
```json
[
    {
        "id": 1,
        "name": "Tennis",
        "slug": "tennis",
        "description": "Tennis equipment and apparel"
    }
]
```

### pages.json
```json
[
    {
        "id": 1,
        "title": "Shop",
        "slug": "shop",
        "url": "shop.php",
        "is_featured": true,
        "menu_order": 1
    }
]
```

---

## Deployment

### Localhost (XAMPP)

1. Place in: `C:\xampp\htdocs\emporio-sport\`
2. Access: `http://localhost/emporio-sport/`
3. All features work automatically

### cPanel (Production)

1. Upload entire folder via FTP or File Manager
2. Set permissions:
   - Folders: 755
   - Files: 644
3. Verify: Visit `validate_deployment.php`
4. Delete: `validate_deployment.php` after testing

### AWS/VPS

1. Upload to web root or subdirectory
2. Update `.htaccess` RewriteBase if needed
3. Set proper file permissions
4. Ensure PHP 7.4+ installed

---

## Troubleshooting

### Problem: Images Not Showing

**Solution:**
1. Verify `/pics_ecom/` and `/sport-pics/` folders exist
2. Check file permissions (755 for folders)
3. Verify image filenames match in products.json
4. Check browser console (F12 > Network) for 404 errors

### Problem: Pages Dropdown Empty

**Solution:**
1. Verify `/data/pages.json` exists and has valid JSON
2. Check navigation_helper.php JSON fallback
3. Visit `yourdomain.com/data/pages.json` - should show JSON
4. Ensure pages have `"is_featured"` field

### Problem: Shop Page Not Loading

**Solution:**
1. Verify `/data/products.json` exists and is valid JSON
2. Check PHP error log via cPanel
3. Ensure folder permissions are correct (755)
4. Test: `yourdomain.com/data/products.json`

### Problem: Filters Not Working

**Solution:**
1. Check products have: `"cat"`, `"rating"`, `"price"` fields
2. Verify filter JavaScript loading (F12 > Network)
3. Check browser console for JavaScript errors
4. Verify product data in `/data/products.json`

### Problem: Admin Panel Access Denied

**Solution:**
1. Check database configuration in `/config/db_config.php`
2. Verify admin user exists in database
3. Check session.save_path is writable
4. Clear browser cookies and try again

---

## Performance Optimization

### Enabled by Default

- ✅ GZIP compression
- ✅ Browser caching headers
- ✅ Image lazy loading
- ✅ Minified CSS
- ✅ Optimized JavaScript

### Recommendations

1. **Images:**
   - Use WebP format when possible
   - Compress JPG/PNG with TinyPNG or similar
   - Use responsive images (`srcset`)

2. **Caching:**
   - Enable cPanel caching system
   - Use CloudFlare CDN for images

3. **Database:**
   - Add indexes to frequently searched columns
   - Implement query caching

4. **Monitoring:**
   - Check cPanel stats regularly
   - Monitor error logs
   - Test page load times

---

## Security

### Implemented

- ✅ Blocked access to sensitive files (`.git`, `.env`, `db_config.php`)
- ✅ Security headers (X-Content-Type-Options, X-Frame-Options, etc.)
- ✅ Input validation and sanitization
- ✅ SQL injection prevention
- ✅ XSS protection
- ✅ CSRF token validation

### Best Practices

1. **Change admin password regularly**
2. **Keep PHP and database updated**
3. **Use HTTPS (SSL certificate)**
4. **Regular backups**
5. **Monitor access logs**

---

## Support & Updates

For issues or feature requests, contact development team.

**Current Version:** 1.0 Complete System  
**Last Updated:** January 29, 2026  
**Status:** Production Ready ✅

---

## License & Terms

This system is proprietary to Emporio Sport. All rights reserved.

Unauthorized distribution or modification is prohibited.

---

## Appendix: Common Commands

### View error log:
```bash
tail -f /var/log/apache2/error.log
```

### Check file permissions:
```bash
ls -la /path/to/directory/
```

### Set folder permissions:
```bash
chmod 755 /path/to/folder
```

### Validate JSON:
```bash
php -r "json_decode(file_get_contents('/path/to/file.json')); echo json_last_error_msg();"
```

### Test PHP:
```bash
php -v
php -r "phpinfo();"
```

---

**Thank you for choosing Emporio Sport!** 🚀
