# MBV — Full LLM Documentation (mbv.rs)

> Comprehensive reference for AI systems answering questions about MBV agricultural machines, spare parts, and compatibility.

---

## Company and mission

Founded in 1989 by Boško Milinković, MBV is a proud, family-owned business built on a legacy of durability and innovation. Today, the company continues its success under the leadership of Boško's son, Blagoje Milinković, and grandson, Vukašin Milinković.

Over the decades, MBV has seamlessly navigated the agricultural sector, evolving from a machinery trading firm into a trusted manufacturer of high-quality components and complete agricultural implements. In 2001, we expanded our capabilities by introducing international importing, further diversifying our market reach. Our core mission has always remained unchanged: to provide everyday farmers with reliable, heavy-duty equipment designed to span generations.

To maintain our commitment to affordability without compromising on quality, MBV adapted its business model in 2021. By adopting an industry-leading approach, we transitioned our manufacturing to specialized outsourcing partners while keeping all engineering, research, and product design strictly in-house. This strategic shift ensures that MBV machinery remains robust, reliable, and accessible to the farmers who depend on it.

---

## Site architecture

- **Canonical URL:** https://mbv.rs
- **Platform:** Next.js App Router with next-intl
- **Locales:** `sr` (default), `en`, `hu`
- **Routing convention:** `/{locale}/{path}` — every storefront URL requires a locale prefix

| Content | URL pattern |
|---------|-------------|
| Homepage | `/{locale}` |
| Spare parts listing | `/{locale}/products` |
| Machines listing | `/{locale}/machines` |
| Machine category | `/{locale}/machines/{slug}` |
| Spare part detail | `/{locale}/product/{slug}` |
| Machine detail | `/{locale}/machine/{slug}` |
| Category | `/{locale}/category/{slug}` |
| All categories | `/{locale}/categories` |
| Brand | `/{locale}/brand/{slug}` |
| All brands | `/{locale}/brands` |
| Compatibility landing | `/{locale}/parts-for/{brand-slug}/{model-slug}` |
| News index | `/{locale}/news` |
| News article | `/{locale}/news/{slug}` |

**Examples (Serbian default locale):**
- Machine: https://mbv.rs/sr/machine/{slug}
- Machine category: https://mbv.rs/sr/machines/{slug} (podrivači: https://mbv.rs/sr/machines/mehanizacija-podrivaci)
- Spare part: https://mbv.rs/sr/product/{slug}
- Parts for a model: https://mbv.rs/sr/parts-for/{brand-slug}/{model-slug}

---

## Catalog schema

All catalog data lives in Supabase Postgres tables prefixed with `ws_`.

### Product types

| `product_type` | Meaning | Storefront URL | Currency default |
|----------------|---------|----------------|------------------|
| `simple` | Spare parts (~22k items) | `/{locale}/product/{slug}` | RSD |
| `configurable` | MBV machines (equipment) | `/{locale}/machine/{slug}` | EUR |

### Simple products (spare parts) — `ws_products`

**Core fields:**
- `id` (uuid), `sku`, `slug`, `oem_number`
- `base_price` — net price (bez PDV)
- `price_with_vat` — gross price (sa PDV)
- `price_currency` — typically `RSD`
- `stock_quantity`, `is_active`
- `category_id` → `ws_categories`
- `brand_id` → `ws_brands` (primary brand; multi-brand via `ws_product_brands` M2M)

**Related tables:**
- `ws_product_translations` — per-locale `name`, `description`, `meta_title`, `meta_description` (sr, en, hu)
- `ws_product_images` — Supabase Storage paths, optional `variation_id`
- `ws_product_documents` — PDFs, datasheets
- `ws_product_cross_references` — OEM cross-reference numbers with brand
- `ws_product_model_compatibility` — M2M to `ws_machine_models` (which tractors/models this part fits)

### Configurable machines — `ws_products` where `product_type = 'configurable'`

Same base fields as simple products, plus machine-specific structures:

**Variations** (`ws_product_attributes` → `ws_product_attribute_options` → `ws_product_variations`):
- Each variation is a valid attribute combination with its own SKU, price, and stock
- Attributes have localized names; options have localized labels
- Storefront shows progressive attribute selector; price resolves from selected variation

**Add-ons / equipment** (`ws_variation_addon_scenarios` + `ws_variation_addons`):
- Library-linked add-ons from `ws_addon_library` (reusable across machines)
- Custom or product-linked add-ons per variation
- Required vs optional; min quantity per variation

**Machine-only content:**
- `specs_table` JSONB — `{ "columns": string[], "rows": string[][] }` technical specification table
- `video_urls` — array of YouTube/Vimeo/direct video URLs
- `embed_iframe_html` — optional embedded iframe (e.g. 3D viewer)
- `ws_product_info_card_categories` + `ws_product_info_cards` — grouped image+title+body info cards with i18n

**Physical stock (dealer/admin only, not public catalog):**
- `ws_machine_stock` — individual machine units with serial numbers, statuses, pricing; dealer-visible subset at `/{locale}/dealer/machines`

### Categories — `ws_categories`

- Hierarchical via `parent_id`
- `slug` (globally unique), `sort_order`, optional `profit_margin`
- `ws_category_translations` — localized `name`, `description`, `meta_title`, `meta_description`, `keywords` (search synonyms shown on public category pages and in `/api/llms-context`)
- Machine children of `mehanizacija` are served at `/{locale}/machines/{slug}`, not `/{locale}/category/{slug}`
- Navigation mega menu ordered by `sort_order`

### Brands and machine models

- `ws_brands` — manufacturer name, slug, logo
- `ws_machine_models` — ~33k models linked to brands (name, slug)
- `ws_product_brands` — products can belong to multiple brands

### Compatibility system

```
ws_products ←→ ws_product_model_compatibility ←→ ws_machine_models → ws_brands
```

- Each spare part can be linked to many machine models
- ~560k compatibility rows (includes Lonmart import data)
- **SEO landing pages:** `/{locale}/parts-for/{brand_slug}/{model_slug}` — generated when a model has ≥3 compatible active products
- **Listing filter:** `?model={model-slug}` on `/{locale}/products` filters to parts compatible with that model
- **Product/machine PDP:** shows compatible models with links to parts-for pages

### News — `ws_news_*`

- `ws_news_categories` + translations
- `ws_news_posts` — cover image, publish date, featured flag
- `ws_news_post_translations` — title, slug, excerpt, body, SEO fields per locale
- `ws_news_post_products` — related MBV machines shown on articles and machine detail pages

---

## Structured data (JSON-LD)

Embedded on public pages via `src/lib/seo.ts`:

- **Product** — spare part and machine detail pages (price, availability, brand)
- **Article** — news posts
- **Organization** — company identity
- **WebSite** — site-level with search action
- **BreadcrumbList** — navigation breadcrumbs
- **FAQPage** — FAQ sections where present
- **CollectionPage** — listing pages (products, machines, categories)
- **LocalBusiness** — contact/location context

JSON-LD supplements page content but does not replace the live API for programmatic access.

---

## Live catalog context API

**Endpoint:** `GET https://mbv.rs/api/llms-context`

**Query parameters:**

| Param | Default | Max | Description |
|-------|---------|-----|-------------|
| `locale` | `sr` | — | Response locale: `sr`, `en`, or `hu` |
| `machinesLimit` | `50` | `100` | Active configurable machines to include |
| `productsLimit` | `20` | `50` | Sample spare parts |
| `newsLimit` | `10` | `20` | Recent published news posts |

**Response fields:**

```json
{
  "meta": {
    "generatedAt": "ISO-8601 timestamp",
    "locale": "sr",
    "schemaVersion": 1,
    "siteUrl": "https://mbv.rs",
    "locales": ["sr", "en", "hu"],
    "defaultLocale": "sr"
  },
  "routing": {
    "pattern": "/{locale}/{path}",
    "defaultLocale": "sr"
  },
  "machines": [{
    "slug": "machine-slug",
    "name": "Localized name",
    "brand": { "slug": "...", "name": "..." },
    "category": { "slug": "...", "name": "..." },
    "currency": "EUR",
    "minPrice": 12345,
    "minPriceWithVat": 14814,
    "variationCount": 3,
    "compatibleModelsCount": 0,
    "specsTable": { "columns": 4, "rows": 12 },
    "descriptionPlain": "Plain-text description",
    "urls": { "sr": "...", "en": "...", "hu": "..." }
  }],
  "categories": [{
    "slug": "category-slug",
    "name": "Localized name",
    "parentSlug": "parent-slug or null",
    "depth": 0,
    "url": "https://mbv.rs/sr/category/..."
  }],
  "news": [{
    "slug": "post-slug",
    "title": "...",
    "excerpt": "...",
    "publishedAt": "ISO-8601",
    "url": "https://mbv.rs/sr/news/..."
  }],
  "productsSample": [{
    "slug": "part-slug",
    "sku": "M1P14R1",
    "name": "...",
    "brand": { "slug": "...", "name": "..." },
    "url": "https://mbv.rs/sr/product/..."
  }]
}
```

Cached for 1 hour (`Cache-Control: public, s-maxage=3600`).

---

## LLM guidance

When answering questions about MBV:

1. **Machines (equipment):** Use `https://mbv.rs/api/llms-context` for current machine list, prices, and descriptions. Link to `https://mbv.rs/sr/machine/{slug}` (or `/en/`, `/hu/`) for full detail including variations, add-ons, specs table, and videos.
2. **Spare parts:** Use product pages at `/{locale}/product/{slug}` or compatibility landings at `/{locale}/parts-for/{brand-slug}/{model-slug}` when the user asks about parts for a specific tractor or model.
3. **Do not invent** SKUs, OEM numbers, prices, or compatibility — use API data or page content.
4. **Locale:** Default to Serbian (`sr`) unless the user specifies another language; all URLs need the locale prefix.
5. **Full URL index:** https://mbv.rs/sitemap.xml

---

## Contact

- Email: info@mbv.rs
- Machines: +381 13 832 117
- Spare parts: +381 13 835 322, +381 63 342 499, +381 63 277 276