Reklamator/specs/002-product-list/data-model.md

Data Model: Product Selection Landing Page

Feature: 002-product-list | Date: 2025-10-17

Overview

This feature reuses the existing Product entity from feature 001-build-an-application with a minor extension. No new entities are created.

Existing Entity: Product

Source: app/models/product.py (from feature 001)

Attributes (relevant to this feature):

Attribute	Type	Required	Description
product_id	str	Yes	Unique identifier (e.g., "001-acme-app")
name	str	Yes	Display name for the product
submission_url_slug	str	Yes	URL segment for submission form
status	str	Yes	"active" or "archived"
description	str	No	Brief product description (optional)

Storage: File-based YAML at data/products/{product-id}/config.yaml

Example:

product_id: "001-acme-app"
name: "Acme Application"
submission_url_slug: "acme-app"
status: "active"
description: "Enterprise resource planning system"

---

Model Extension

New Class Method: load_active()

Purpose: Load and return only active products with valid submission URLs, sorted for display.

Signature:

@classmethod
def load_active(cls) -> list[Product]:
    """Load all active products, sorted alphabetically by name then product_id."""

Returns: List of Product instances where:

• status == 'active'
• submission_url_slug is present and valid
• Sorted by: (name.lower(), product_id)

Implementation Location: app/models/product.py

Usage Example:

from app.models.product import Product

# In route handler
products = Product.load_active()
# Returns sorted list of active products ready for display

---

Data Flow

Landing Page Load Sequence

1. Request: User navigates to /
2. Route Handler: app/routes/landing.py
   • Calls Product.load_active()
3. Data Loading: Product model
   • Reads all data/products/*/config.yaml files
   • Filters: status == 'active' AND submission_url_slug exists
   • Sorts: By (name.lower(), product_id)
4. Response: Render template with product list
   • Pass products to templates/landing/index.html
   • Template loops over products, displays name/description/link

Diagram

User → GET / → landing.py → Product.load_active() → [Product, Product, ...]
                                  ↓
                            Templates (Jinja2) → HTML Response → User

---

Validation Rules

Product Visibility (for landing page)

A product is visible on the landing page if and only if:

1. status == 'active' (FR-003)
2. submission_url_slug is not None/empty (FR-015)

Products failing either condition are excluded from the list.

Sorting Rules (FR-009)

Products are sorted by:

1. Primary: name (case-insensitive alphabetical)
2. Secondary: product_id (alphabetical, for ties)

Examples:

• Input: [{"name": "Zebra", "product_id": "001"}, {"name": "Apple", "product_id": "002"}]

• Output: [{"name": "Apple", ...}, {"name": "Zebra", ...}]

• Input: [{"name": "App", "product_id": "002"}, {"name": "App", "product_id": "001"}]

• Output: [{"name": "App", "product_id": "001"}, {"name": "App", "product_id": "002"}]

---

No New Entities

This feature introduces no new entities. All data structures are reused from feature 001:

• Product entity (extended with load_active() method only)
• File-based YAML storage (unchanged)
• No database tables, no new data files

---

Testing Considerations

Test Data Requirements

For comprehensive testing, create products with:

• Various statuses: "active", "archived"
• With/without descriptions
• With/without valid submission_url_slug
• Duplicate names (to test secondary sort)
• Various name cases ("Apple", "apple", "APPLE")

Expected Behaviors

Scenario	Expected Result
Product with status: active	Included in list
Product with status: archived	Excluded from list
Product with missing submission_url_slug	Excluded from list
Products with same name	Sorted by product_id
Empty product directory	Returns empty list

Reference Tests: See tests/contract/test_landing_routes.py for data model validation tests.