SkinbaseNova/.copilot/artworks.md

Artworks Module – Canonical Architecture (SkinBase)

Authoritative documentation for Copilot AI agent This file defines the single source of truth for the artworks domain. All generated code MUST follow this document.

---

1. Purpose

The Artworks module is the core content system of SkinBase.

It must support:

• high-read traffic (browse/search)
• safe moderation (soft deletes, approvals)
• multilingual content
• SEO-friendly URLs
• scalable statistics
• future extensions (tags, EXIF, search engines)

Legacy tables must NOT influence new code.

---

2. Core Design Principles (DO NOT VIOLATE)

1. Single responsibility per table
2. No counters on hot tables
3. Soft deletes on user-generated content
4. No legacy fields
5. Slug-based routing only
6. FK integrity everywhere
7. Indexes optimized for browsing
8. Stats updated asynchronously

---

3. Database Schema (Canonical)

3.1 artworks (CORE TABLE)

Purpose: Stores the authoritative artwork entity.

artworks

Fields:

Field	Type	Notes
id	bigint	Primary key
user_id	bigint	Owner
title	varchar(150)	Default language
slug	varchar(160)	UNIQUE, URL
description	text	Optional
file_name	varchar	Original file
file_path	varchar	Storage path
file_size	bigint	Bytes
mime_type	varchar(64)	e.g. image/jpeg
width	int	Pixels
height	int	Pixels
is_public	boolean	Visibility
is_approved	boolean	Moderation
published_at	datetime	SEO timing
created_at	datetime
updated_at	datetime
deleted_at	datetime	Soft delete

Indexes:

• UNIQUE(slug)
• (is_public, is_approved, published_at)
• deleted_at

---

3.2 artwork_translations

Purpose: Multilingual titles and descriptions.

artwork_translations

Field	Type
artwork_id	FK
locale	char(2)
title	varchar
description	text
deleted_at	datetime

Rules:

• One row per (artwork_id, locale)
• Default language lives in artworks

---

3.3 artwork_stats

Purpose: High-write counters isolated from core table.

artwork_stats

Field	Type
artwork_id	PK + FK
views	bigint
downloads	bigint
favorites	bigint
rating_avg	float
rating_count	int

Rules:

• NO soft deletes
• Updated via jobs / async
• Never eager-loaded by default

---

3.4 artwork_category

Purpose: Many-to-many relation with categories.

artwork_category

Field	Type
artwork_id	FK
category_id	FK

Rules:

• Categories handle hierarchy
• Artworks can belong to multiple categories

---

3.5 artwork_comments

Purpose: User comments with moderation.

artwork_comments

Field	Type
artwork_id	FK
user_id	FK
content	text
is_approved	boolean
deleted_at	datetime

---

3.6 artwork_downloads

Purpose: Audit log of downloads.

artwork_downloads

Field	Type
artwork_id	FK
user_id	nullable
ip	binary(16)
user_agent	varchar
created_at	datetime

Rules:

• Append-only
• No soft deletes
• Used for abuse detection & stats aggregation

---

4. Eloquent Models (REQUIRED)

4.1 Artwork Model

App\Models\Artwork

Traits:

• SoftDeletes

Relationships:

belongsTo(User::class)
hasMany(ArtworkTranslation::class)
hasOne(ArtworkStats::class)
belongsToMany(Category::class)
hasMany(ArtworkComment::class)
hasMany(ArtworkDownload::class)

Required Scopes:

public function scopePublic($q)
public function scopeApproved($q)
public function scopePublished($q)

---

4.2 ArtworkTranslation

App\Models\ArtworkTranslation

• SoftDeletes
• BelongsTo Artwork

---

4.3 ArtworkStats

App\Models\ArtworkStats

• No SoftDeletes
• BelongsTo Artwork

---

4.4 ArtworkComment

App\Models\ArtworkComment

• SoftDeletes
• BelongsTo Artwork
• BelongsTo User

---

4.5 ArtworkDownload

App\Models\ArtworkDownload

• Append-only
• BelongsTo Artwork

---

5. Query Rules (IMPORTANT)

Public browsing MUST always include:

WHERE
  deleted_at IS NULL
  AND is_public = 1
  AND is_approved = 1

NEVER:

• eager-load stats on lists
• update counters inline
• expose IDs in URLs

---

6. Routing Rules

Canonical URLs

/{content_type}/{category_path}/{artwork_slug}

Example:

/photography/abstract/dark/night-city

Slug uniqueness is GLOBAL.

---

7. Search Rules

• Use MySQL FULLTEXT as fallback
• Prefer external search engines later
• Never search on file_name or paths

---

8. Caching Rules

• Category listings → Redis
• Homepage feeds → Redis
• Artwork stats → cached
• DB is source of truth

---

9. Soft Delete Behavior

Action	Result
Soft delete artwork	Hidden from public
Restore	Fully restored
Force delete	Rare, GDPR only

SEO:

• Soft-deleted artworks → 410 or 301

---

10. Forbidden Patterns (NEVER GENERATE)

❌ Counters on artworks ❌ IDs in URLs ❌ Hard deletes ❌ Category logic inside artworks ❌ Mixed language columns ❌ MyISAM ❌ Polymorphic abuse

---

11. Future Extensions (Allowed)

Copilot MAY extend with:

• artwork_tags
• artwork_exif
• artwork_versions
• artwork_reports
• external search engines

BUT must not modify core tables without migrations.

---

12. Final Rule (MANDATORY)

If generated code conflicts with this document, THIS DOCUMENT WINS.