# SEO Implementation Specification — Tabriz Soghat

## Goal

Make the Laravel store technically crawlable, semantically clear, internally well-linked, and suitable for product/category organic search.

Important: do not assume the existing implementation. Inspect it first and modify only what is needed.

## 1. Technical SEO

Audit and fix:

- canonical URL on every indexable page
- HTTPS canonical consistency
- HTTP -> HTTPS redirect
- www/non-www consistency
- trailing slash consistency
- duplicate query-string URLs
- pagination behavior
- 404/410 behavior
- soft-404 pages
- noindex behavior for internal/search/filter pages when appropriate
- robots.txt
- XML sitemap
- sitemap exclusion of non-indexable URLs
- stale/invalid sitemap URLs
- correct `lastmod` where meaningful
- hreflang only if multiple language versions actually exist
- Open Graph/Twitter metadata
- mobile viewport and responsive rendering
- broken internal links
- orphan pages

## 2. URL strategy

Do not blindly change existing public URLs.

Preferred principle:
- stable
- human-readable
- deterministic
- lowercase where practical
- no unnecessary query parameters
- one canonical URL per entity

Existing URLs must remain reachable or redirect with 301 when replaced.

For every changed product/category/blog URL:
- create redirect mapping
- preserve old URL compatibility
- update internal links
- update canonical
- update sitemap

Consider a reusable redirect table/model if the project already has a routing/redirect mechanism.

## 3. Meta tags

Implement reusable SEO metadata resolution.

Each indexable page should support:
- title
- meta description
- canonical
- robots
- OG title
- OG description
- OG image
- OG URL
- Twitter card metadata

Resolution order:
1. explicit entity/page SEO fields
2. entity-derived default
3. global fallback

Do not allow duplicate `<title>` tags.

Recommended title generation examples:
- Homepage: `خرید سوغات تبریز | فروشگاه اینترنتی سوغات اصل تبریز`
- Category: `خرید {category} تبریز | قیمت انواع {category}`
- Product: `خرید {product name} | قیمت و مشخصات`
These are examples only; derive from actual product/category naming.

## 4. Heading structure

Rules:
- exactly one meaningful H1 per primary page
- H1 must match search intent, not just branding
- do not hide primary content in JS
- headings must follow logical hierarchy

Product:
H1 -> product name

Category:
H1 -> category commercial topic

Blog:
H1 -> article title

## 5. Category SEO

Every important commercial category should have:
- unique title
- unique meta description
- H1
- intro copy
- product listing
- child category links
- relevant internal links
- optional FAQ
- canonical URL

Avoid thin category pages.

Do not index empty categories as normal commercial landing pages unless there is a deliberate SEO strategy for them.

## 6. Product SEO

Each product should support:
- unique title
- unique description
- H1
- price
- availability
- SKU
- weight/variant data if applicable
- ingredients/features where applicable
- image alt
- related products
- breadcrumb
- Product JSON-LD
- Offer JSON-LD
- Review/AggregateRating only when genuine review data exists

Never invent reviews, ratings, availability or brand data.

## 7. Structured data

Implement and validate:
- `Organization` or `LocalBusiness` if appropriate
- `WebSite`
- `BreadcrumbList`
- `Product`
- `Offer`
- `Article` / `BlogPosting`
- `FAQPage` only when the visible page genuinely contains those FAQs and the markup is policy-compliant

Keep JSON-LD synchronized with visible page values.

Important:
- price currency must match the actual application currency
- availability must match actual inventory state
- SKU must match application data
- product name/image must match page
- do not output fake aggregate ratings

## 8. Images

Audit:
- file names
- dimensions
- compression
- WebP/AVIF where supported
- `alt`
- lazy loading below the fold
- width/height to reduce layout shift
- responsive image sizes
- product main image quality
- Open Graph image

Do not keyword-stuff alt text.

## 9. Internal linking / topical clusters

Implement reusable related links.

Core cluster concept:

Homepage
-> category
-> subcategory
-> product

Blog
-> relevant category
-> relevant product

Product
-> category
-> sibling products
-> related blog articles

Use contextual anchor text.

Avoid giant sitewide link blocks that look unnatural.

## 10. Breadcrumbs

Render visible breadcrumbs and corresponding `BreadcrumbList` JSON-LD.

Example:
Home > سوغات تبریز > نقل > نقل گردویی زعفرانی

Do not put irrelevant ancestors in breadcrumbs.

## 11. Blog-to-commerce linking

The blog system must allow editors to link:
- article -> category
- article -> product
- article -> other article

Product/category pages should optionally expose related articles.

This is a core SEO requirement, not a decorative feature.

## 12. Search/filter pages

Inspect product filtering implementation.

Prevent uncontrolled crawlable URL combinations.

Decide per filter:
- canonical to category
- noindex,follow
- indexable landing page
based on actual business/search value.

Do not automatically index every filter combination.

## 13. Performance

Inspect:
- database query count / N+1
- image payload
- render blocking assets
- page cache where safe
- cache invalidation
- critical CSS/JS strategy
- Core Web Vitals

Do not sacrifice correctness for arbitrary caching.

## 14. SEO admin controls

Add SEO fields to entities that actually need editor control:
- categories
- products where appropriate
- blog posts
- static pages if system supports them

Recommended fields:
- seo_title
- seo_description
- seo_image
- canonical_url
- robots_index
- robots_follow
- maybe structured-content fields only where justified

Use nullable fields and global fallbacks.

## 15. Automated checks

Add tests for:
- canonical output
- unique title generation logic
- sitemap contains canonical URLs
- noindex excludes intended pages
- redirects return 301
- product JSON-LD values
- category canonical
- article JSON-LD
- breadcrumb JSON-LD
- no duplicate H1 where testable