Parts & Accessories Catalog

VW Polo 6R Parts and Accessories Catalog

A comprehensive, multilingual catalog of genuine OEM parts and accessories for the Volkswagen Polo 6R/6C, built with a fully decoupled headless architecture. The Astro-powered static frontend consumes a Laravel REST API at build time, producing pure HTML pages with zero runtime database queries. While not an e-commerce site, it shares many features with online stores — product listings, filtering, search, detailed specifications — except for payment processing.

The project has evolved through several iterations: from an early Vue 2 SPA, through Vue 3, to the current Astro 6 SSG setup with Vue 3 islands for interactive components.

Architecture: Headless CMS + Static Frontend

The system is split into two independent repositories:

Frontend (catalog.polo.blue) — Astro 6 static site generator with Vue 3 components, UnoCSS styling, and a custom design system. All data is fetched from the API exclusively during the build step. The browser never contacts the backend directly (except for client-side tools like the PR Codes Decoder).

Backend — Laravel 13 application serving a REST API and a Filament 5 admin panel. Manages products, categories, translations, media, SEO data, and site deployments. Backed by MySQL, Redis (queues via Laravel Horizon for background jobs like image conversion, translations, and site builds), and Cloudflare R2 for CDN storage. Site deploys can be triggered directly from the admin panel.

This separation means the frontend is a pure static site — fast, secure, and globally cacheable via Cloudflare CDN.

Image Pipeline & CDN

A key challenge was optimizing images given the extensive product catalog and predominantly mobile traffic. The solution evolved from build-time compression via Sharp/Astro to a backend-driven pipeline:

1. Upload — Images are stored on Cloudflare R2 (S3-compatible) via Spatie Media Library
2. Conversion — Background queues generate responsive thumbnails in modern formats (AVIF with WebP fallback)
3. Delivery — Served from cdn.polo.blue with denormalized URLs stored directly on Product/Category models to eliminate JOIN queries in list views
4. Monitoring — A CDN Stats widget in the admin panel tracks total storage, per-model breakdown, and the percentage of products with all AVIF conversions complete

WebP serves as a fallback to AVIF due to its still limited indexing in Google Image Search.

Multilingual Support & Automated Translations

The catalog supports three languages — English, Polish, and German. All translatable content (products, categories, colors, materials, PR codes, FAQ entries, and more) shares a single unified translation system, so adding a new language requires no schema changes.

• DeepL API automatically translates content from English into Polish and German via queued background jobs
• AI-generated descriptions use a multi-provider fallback chain to generate English copy, which is then translated by DeepL
• Per-locale URL structures (/ for EN, /pl/ for Polish, /de/ for German) with properly configured hreflang tags
• Static UI strings loaded from JSON files, content translations served already localized by the API

Performance Optimizations

Split Build System

Building all three locales in a single Astro pass caused memory exhaustion (10-20 GB RAM). The solution: a custom split build script that processes one locale at a time, runs Pagefind indexing per locale, then merges everything into the final dist/ directory. Total build time: ~4-5 minutes for all locales.

API Call Reduction

A category prefetch cache fetches all products per main category in a single API call, then filters locally. This reduced ~60 individual API requests to a handful of batch calls during build.

Frontend Performance

• content-visibility: auto on off-screen product rows to reduce rendering cost
• Sidebar collapse state restored from localStorage before first paint to prevent CLS
• Font preloading (VW brand fonts), preconnect to CDN and analytics domains
• Vite manual chunks separating vendor code (Vue, design system) from page code
• First 3 product images loaded eagerly, with fetchpriority="high" on the very first image; rest lazy-loaded

SEO & Discoverability

Strong SEO has been a primary driver of traffic, especially from image search engines. Key strategies include:

• Structured Data (JSON-LD) — Rich @graph markup with IndividualProduct (not Product, to signal non-merchant catalog), BreadcrumbList, ItemList for category pages, and Organization entities
• XML Sitemaps — Generated server-side per locale and type (products, categories, pages), fetched at build time with XSL stylesheets for browser-readable display
• llms.txt — AI/LLM discoverability files following the llmstxt.org specification
• Internal linking — Related Products, Similar Products, and in-category navigation buttons (validated via A/B testing) improve link equity and user flow
• Pagefind — Offline full-text search indexed per locale, with no external dependencies
• SEO Dashboard — Admin panel widgets audit short/long titles, missing descriptions, and data completeness across all three languages

Interactive Tools

Three client-side Vue 3 tools enhance the catalog’s utility:

• Tire & Wheel Calculator — Compares two tire/wheel configurations, calculates diameter differences and speedometer deviation, with SVG visualization
• Power Converter — Converts between HP, kW, and PS with a visual bar chart
• PR Codes Decoder — Decodes VW factory option codes (3-character codes) by querying the API, with client-side caching

These tools are isolated in a separate Astro route to prevent their CSS (~25 KB) from affecting the main catalog pages.

Backend & Admin Panel

The backend, powered by Laravel 13 and Filament 5, delivers the REST API and provides a comprehensive admin panel organized into functional clusters:

Content Management

• Product management with detailed specifications, PR codes, engine compatibility, and multi-language support
• Hierarchical category organization with icon and OG image management
• CMS page builder with 13 block types (hero, jumbotron, carousel, CTA, FAQ, statistics, etc.)
• Translation management with DeepL batch automation and protection flags for critical translations

REST API

The API uses configurable response presets to control the depth of included data per endpoint — keeping responses lean for listings and rich for detail views. HTTP cache headers are tuned per route to maximize CDN hit rates.

Analytics & Monitoring Dashboards

• Google Analytics 4 — Page views, visitors, sessions, devices, top referrers, geographic data (14 widgets)
• Google Search Console — Clicks, impressions, CTR, average position, top pages and queries
• Core Web Vitals — CLS, LCP, INP time-series tracking
• Google AdSense — Multi-site earnings tracking with alerts for revenue drops

Operations & Maintenance

• One-click site deploy triggering Astro builds via queued jobs (separate site-build queue to avoid blocking translation/media jobs)
• Cloudflare cache purging by URL, prefix, or model type
• Database backup/restore utilities
• Activity logging and full audit trail
• Data completeness dashboard auditing missing media, translations, descriptions, and link quality

FAQ Knowledge Base

The catalog includes an integrated FAQ system providing technical specifications and how-to guides for VW Polo 6R. Content is organized by product categories (tires, wheels, engine oil, HVAC, brakes, suspension, body parts) and supports multilingual display with links to detailed blog posts.

Deployment

The frontend uses an atomic deployment strategy:

• Push to main triggers GitHub Actions
• Astro split build runs on the hosting server
• Each release gets a timestamped directory; public_html is a symlink
• Rollback takes under 1 second by re-pointing the symlink to a previous release

Used Technologies

Strong SEO, image optimization, and structured data have driven significant organic traffic — particularly from image search engines — while the headless architecture keeps the site fast, secure, and easy to maintain.