# Filaments.gg MVP Design

## Purpose

Filaments.gg is a technical discovery and comparison platform that helps 3D-printing users choose a filament for an application and printer, understand trade-offs, compare products, find alternatives, and buy through useful retailer links.

The public experience must feel like a structured product tool—closer to PCPartPicker or RTINGS than an affiliate-content site. Dense technical information must remain easy to scan on desktop and mobile.

## MVP boundary

V1 includes:

- A public homepage, catalog, filtering, search, material explorer, product pages, material pages, printer compatibility, product comparison, material comparison, alternatives, and an explainable filament finder.
- A protected admin portal for manufacturers, materials, products, colors, spool variants, images, retailers, offers, printers, and compatibility overrides.
- Repeatable import/backfill scripts to load and safely update the initial catalog of roughly 10–15 manufacturers, 100–200 popular products, major material families, and popular consumer printers.
- Affiliate offers that show best price, other retailers, price per kilogram, stock state, update date, and a disclosure.
- Server-rendered, indexable public pages and purposeful SEO metadata.

V1 does not include public user accounts, saved printers, favourites, reviews, community print profiles, alerts, live price crawling, a proprietary rating score, or physical test results.

## Stack

- Nuxt 3 with Vue and TypeScript.
- Tailwind CSS and shadcn-vue for the component system.
- Neon Postgres and Drizzle ORM for persistent data and migrations.
- Better Auth for authentication, initially limited to administrator access.
- S3-compatible object storage for product images, manufacturer logos, and future test assets.

## Architecture

The application is a single Nuxt project with public server-rendered routes, server API routes, protected admin routes, Drizzle database access, and an S3 adapter. Server code owns database access, recommendation evaluation, affiliate URL handling, and signed-upload creation; browser code never receives database or bucket credentials.

Domain boundaries are deliberately small:

1. **Catalog** owns manufacturers, materials, products, variants, colors, images, and technical specifications.
2. **Commerce** owns retailers and product offers.
3. **Compatibility** owns printer capabilities and explicit product/printer overrides.
4. **Discovery** owns searchable/filterable projections, finder rules, comparisons, and alternatives.
5. **Administration** owns authenticated maintenance flows and import operations.

## Data design

All primary entities use UUID primary keys and immutable unique slugs. Values with inconsistent manufacturer coverage are nullable; unknown data is rendered as “Not provided,” never invented.

Canonical units:

- Temperatures: Celsius.
- Dimensions: millimetres.
- Weight: grams.
- Density: g/cm³.
- Prices: integer minor currency units plus ISO currency.
- Price per kilogram: computed from the current offer and spool weight, never manually persisted as a second source of truth.

Fields used for filters or comparisons use typed nullable columns. `raw_specs` JSON stores uncommon or manufacturer-specific fields and preserves source values without using an unqueryable generic EAV schema.

Core catalog entities:

- `manufacturers`: name, slug, website, logo asset, description.
- `materials`: family/subtype, characteristics, typical use cases, print requirements, and reference properties.
- `products`: a purchasable filament line linked to one manufacturer and material, with summary, published state, core mechanical properties, speed/flow fields, and raw specifications.
- `product_print_settings`: nozzle/bed/chamber temperatures plus enclosure, hardened-nozzle, drying, and AMS/MMU requirements.
- `product_spools`: weight, dimensions, material, and notes.
- `colors` and `product_color_variants`: normalized colors and per-product display/color imagery.
- `assets` and `product_images`: S3 object metadata and ordered product imagery.
- `application_tags` and `product_application_tags`: suitable/unsuitable application mapping.

Commerce entities:

- `retailers`: retailer identity, website, country/region support.
- `offers`: product, retailer, region, price, currency, stock status, shipping note, affiliate URL, and last update time.

Compatibility entities:

- `printers`: manufacturer, model, maximum nozzle and bed temperature, enclosure status, nozzle details, multi-material support, spool limitations, and notes.
- `printer_product_compatibility`: explicit `compatible`, `requirements`, or `not_recommended` status with structured warnings and notes.

Discovery entities:

- `product_relations`: curated similar and alternative relations, including overall, cheapest, premium, closest specification, closest color, and high-speed categories.

Better Auth owns its authentication tables. An application role check permits only administrators to access `/admin/**` and administrative APIs.

## Public routes and behaviour

- `/` — Finder/search entry, quick need categories, featured products, comparisons, alternatives, and recent additions.
- `/filaments` — Filterable catalog with URL-backed filters.
- `/filament/:manufacturer/:slug` — Product detail, specs, print/drying guidance, compatibility, applications, offers, similar products, and alternatives.
- `/materials` and `/materials/:slug` — Material database and structured material pages.
- `/filaments/:facet` — Curated property views only where enough editorially useful content exists.
- `/find` — Multi-step finder with editable answers and shareable state.
- `/compare/:slugs` — Product comparison for two to four products, plus separate material-comparison handling for canonical material pairs.
- `/alternative/:product` — Alternative categories with reasoned explanations.
- `/printer/:manufacturer/:model/filaments` — Printer-specific compatibility listing.
- `/search` — Global search grouped by products, manufacturers, materials, colors, and printers.

Public page data is server-rendered. Comparison and alternative pages remain indexable only for useful, canonical combinations; low-value query states use canonical URLs or `noindex` to avoid thin-page growth.

## Finder and compatibility logic

The finder is deterministic and explainable. It converts answers about application, environment, heat, impact, flexibility, UV and chemical exposure, desired printability, budget, and printer capability into material constraints and product filters. It ranks matching materials, then products, returning structured reasons, compatibility warnings, price context, and offer links.

Compatibility evaluates a product’s required/recommended temperatures, enclosure, hardened nozzle, drying, AMS/MMU, spool limits, and known overrides against a selected printer. Results always use one of three clear states: fully compatible, compatible with requirements, or not recommended.

## Admin portal and import pipeline

The admin portal supports sparse data and makes unknown fields optional. Administrators can create and edit every V1 catalog/commerce/compatibility entity, upload images with signed S3 URLs, control publication, and manage curated relationships.

Import/backfill scripts consume validated CSV or JSON source files. They upsert by stable manufacturer and product slugs, validate canonical units and required identity fields, report rows rejected with reasons, and are safe to re-run without creating duplicates. Import reports distinguish inserted, updated, skipped, and failed rows.

## Error handling and safety

Public APIs validate input and return typed, user-safe errors. Admin APIs require an authenticated admin session and validate request bodies before mutations. Missing product data produces a stable “Not provided” presentation. Missing offers, images, or optional compatibility data result in useful empty states rather than failures. S3 upload requests validate file type and size server-side before issuing a signed URL.

## Verification

The implementation must include:

- Drizzle schema and migration tests or validation coverage for catalog relationships and required constraints.
- Importer tests covering valid upserts, duplicate re-runs, invalid units, missing identity fields, and error reports.
- Unit tests for price-per-kilogram, finder recommendations, and compatibility states/warnings.
- Route/component tests for filtering, search, product detail unknown fields, comparisons, offers, and admin authorization.
- Accessibility checks for interactive controls and comparison tables.
- A seed-data quality report that identifies published products missing key identity, price, material, or image data.

## Delivery order

1. Foundation, style system, configuration, database, authentication, and S3 integration.
2. Catalog and commerce schema, migrations, seed/import pipeline, and admin maintenance UI.
3. Homepage, catalog filters, product pages, offers, and material explorer.
4. Search, finder, printer compatibility, comparisons, and alternatives.
5. SEO, accessibility, responsive behaviour, fixture/data validation, and deployment readiness.