# Media Asset Management & Digital Asset Pipeline

This document details the media storage architecture, file upload security, digital asset library, and brand crest pipelines of Eniceberny Bakery and Culinary Hub.

---

## 1. Storage Architecture & Driver Abstraction

Eniceberny supports a dual-driver storage architecture configured via the `MEDIA_DISK` environment variable:

```mermaid
graph TD
    A[Staff File Upload /admin/media] --> B[Validation Gate: MIME & Max Size]
    B --> C{MEDIA_DISK Driver?}
    C -->|local / public| D[Local Filesystem storage/app/public/]
    C -->|s3| E[Cloudflare R2 / AWS S3 Bucket]
    D --> F[Public Symlink public/storage/]
    E --> G[Global CDN Edge Cache]
    F --> H[Browser Request via site_logo_url / asset]
    G --> H
```

### Storage Drivers Supported:
1. **Local Persistent Storage (`public`)**:
   - Files stored under `storage/app/public/`.
   - Exposed to the web via `php artisan storage:link` targeting `public/storage`.
2. **Cloud Object Storage (`s3` — Cloudflare R2 / AWS S3)**:
   - Zero-egress fee storage via Cloudflare R2.
   - S3-compatible endpoints configured with `AWS_ENDPOINT`, `AWS_BUCKET`, and `AWS_ACCESS_KEY_ID`.

---

## 2. Centralized Media Library (`/admin/media`)

The Media Library provides a centralized console for all images used across the catalog, marketing banners, and catering galleries:

### Key Media Attributes:
- **`title`**: Descriptive human-readable asset title.
- **`file_path`**: Relative path within the configured storage disk.
- **`disk`**: Driver used (`public` or `s3`).
- **`mime_type`**: Verified MIME type (e.g. `image/jpeg`, `image/png`, `image/webp`).
- **`file_size`**: Byte size of the asset.
- **`dimensions`**: Width and height in pixels (`1200x800`).
- **`folder`**: Logical organization (`branding`, `products`, `gallery`, `cms`).

---

## 3. Brand Identity & Logo Management Engine

The platform features a dedicated dynamic branding engine governed by `SettingController`:

### 3.1 Upload & Replacement Protocol (`POST /admin/settings/logo`)
- **MIME & Extension Security**: Strictly requires `image|mimes:jpeg,png,jpg,webp,svg|max:2048`.
- **Unique Name Generation**: Files are assigned a random cryptographic hash filename, preventing path traversal attacks and browser cache conflicts.
- **Target Folder**: `branding/` directory on the active storage disk.
- **Cache Invalidation**: Automatically clears the `all_site_settings` cache key so all storefront templates reflect the new logo instantly.

### 3.2 Global Helper Functions:
Developers and template designers interact with the logo via clean helper functions:

```php
// Returns the public web URL with fallback to default system asset
$logoUrl = site_logo_url();

// Returns absolute server path for embedding in DomPDF invoices
$logoPath = site_logo_path();

// Returns business title with fallback to "Eniceberny Bakery"
$siteName = site_name();
```

---

## 4. Deletion Guards & Asset Referential Integrity

To prevent broken images on live storefront pages:
- Before any media item can be deleted in `/admin/media`, the system checks whether it is currently bound as a primary image to any `Product`, `Category`, or `HomepageSection`.
- If active dependencies exist, the deletion is rejected with an explanatory message: *"Cannot delete this media asset because it is currently used by [Product Name]"*.
- Destructive actions require explicit confirmation dialogues in the browser.