current state

.copilot/update_user_schema.md

@@ -0,0 +1,312 @@
+# Skinbase – User Schema Review & Upgrade Plan
+
+**Database:** MySQL / Percona 8.x  
+**Project:** Skinbase (new system, no legacy dependencies)  
+**Reviewed tables:** users, user_profiles, user_social_links, user_statistics
+
+---
+
+## 1. Overview
+
+The current user-related database schema is **well designed**, modern, and suitable
+for long-term growth.  
+Key strengths include:
+
+- Clear separation of concerns
+- Proper use of foreign keys and cascading deletes
+- BigInt primary keys
+- Soft deletes on users
+- Migration-friendly legacy password handling
+
+This document summarizes:
+- what is already good
+- recommended optimizations
+- future-proofing steps (non-breaking)
+- performance considerations for scale
+
+---
+
+## 2. users Table
+
+### 2.1 What’s Good
+
+- Unique `username` and `email`
+- `legacy_password_algo` allows smooth migration from old systems
+- `needs_password_reset` improves security posture
+- Role stored as string allows flexibility in early stages
+- Soft deletes enabled
+
+### 2.2 Recommended Indexes
+
+Add indexes for common query patterns:
+
+```sql
+CREATE INDEX idx_users_active ON users (is_active);
+CREATE INDEX idx_users_role ON users (role);
+CREATE INDEX idx_users_last_visit ON users (last_visit_at);
+````
+
+These improve:
+
+* active user filtering
+* admin queries
+* “last seen” or online user features
+
+### 2.3 Future Role Normalization (Planned)
+
+Current approach is fine short-term:
+
+```text
+role = 'user' | 'admin' | 'moderator'
+```
+
+Planned future upgrade:
+
+* `roles` table
+* `user_roles` pivot table (many-to-many)
+
+This allows:
+
+* multiple roles per user
+* temporary or scoped roles
+* better permission modeling
+
+⚠️ No immediate action required — just avoid hard-coding role logic.
+
+### 2.4 Optional Security Enhancements
+
+Recommended additions (optional but advised):
+
+```sql
+last_password_change_at TIMESTAMP NULL,
+failed_login_attempts INT UNSIGNED DEFAULT 0,
+locked_until TIMESTAMP NULL
+```
+
+Enables:
+
+* rate limiting
+* temporary account locking
+* better auditability
+
+---
+
+## 3. user_profiles Table
+
+### 3.1 Strengths
+
+* Clean one-to-one relationship with `users`
+* Public profile data separated from auth data
+* Nullable fields for progressive profile completion
+* Inclusive gender enum with safe default
+* Localization-ready (`language`, `country_code`)
+
+### 3.2 Country Handling Recommendation
+
+Prefer using only:
+
+```text
+country_code (ISO 3166-1 alpha-2)
+```
+
+Benefits:
+
+* language-independent
+* avoids inconsistent country naming
+* easier frontend mapping
+
+`country` text field can be deprecated later if needed.
+
+### 3.3 Avatar & Media Metadata (Future)
+
+Current:
+
+```text
+avatar VARCHAR(255)
+```
+
+Recommended future approach:
+
+```text
+avatar_hash CHAR(64)
+avatar_ext VARCHAR(10)
+avatar_updated_at TIMESTAMP
+```
+
+This aligns with:
+
+* hash-based file storage
+* CDN-friendly URLs
+* cache invalidation control
+
+---
+
+## 4. user_social_links Table
+
+### 4.1 Current Design
+
+* One row per platform per user
+* Unique constraint on `(user_id, platform)`
+* Cascade delete enabled
+
+This is solid.
+
+### 4.2 Platform Normalization (Recommended)
+
+Current:
+
+```text
+platform VARCHAR(32)
+```
+
+Risk:
+
+* inconsistent values (`twitter`, `x`, `Twitter`, etc.)
+
+Options:
+
+**Option A – Enum (simple):**
+
+```sql
+ENUM('twitter','x','instagram','deviantart','artstation','github','website')
+```
+
+**Option B – Reference Table (best long-term):**
+
+* `social_platforms`
+* foreign key `platform_id`
+
+Option B is preferred for Skinbase as platforms evolve.
+
+---
+
+## 5. user_statistics Table
+
+### 5.1 Strengths
+
+* Isolated counters
+* One row per user
+* Minimal row size
+* Clean FK relationship
+
+### 5.2 Performance Warning (Important)
+
+Avoid frequent direct updates like:
+
+```sql
+UPDATE user_statistics SET downloads = downloads + 1;
+```
+
+At scale, this causes:
+
+* row locking
+* write contention
+* degraded performance
+
+### 5.3 Recommended Strategy
+
+* Use **Redis** (or in-memory cache) for real-time increments
+* Periodically flush aggregated values to MySQL
+* Use jobs / cron for batch updates
+
+This ensures:
+
+* fast user interactions
+* scalable statistics tracking
+
+---
+
+## 6. Charset & Collation
+
+Current:
+
+```text
+utf8mb4_unicode_ci
+```
+
+This is correct and safe.
+
+Optional upgrade (MySQL 8+):
+
+```text
+utf8mb4_0900_ai_ci
+```
+
+Benefits:
+
+* newer Unicode rules
+* slightly better performance
+
+Not required immediately.
+
+---
+
+## 7. Tables Planned for Future Expansion
+
+Not required now, but expected as Skinbase grows:
+
+### 7.1 user_activity_log
+
+* logins
+* uploads
+* profile edits
+* moderation actions
+
+### 7.2 user_followers
+
+* artist-to-artist following
+* social graph features
+
+### 7.3 user_settings
+
+* privacy preferences
+* notification settings
+* email subscriptions
+
+These should remain **separate tables** to avoid bloating `users`.
+
+---
+
+## 8. Laravel Implementation Notes
+
+Recommended model casting:
+
+```php
+protected $casts = [
+    'is_active' => 'boolean',
+    'needs_password_reset' => 'boolean',
+    'email_verified_at' => 'datetime',
+    'last_visit_at' => 'datetime',
+];
+```
+
+Best practices:
+
+* Eager load profiles (`with('profile')`)
+* Cache public profile + statistics
+* Keep statistics out of main user queries
+
+---
+
+## 9. Final Verdict
+
+**Schema quality:** Excellent
+**Scalability:** Very good
+**Migration readiness:** Excellent
+**Long-term Skinbase fit:** Excellent
+
+The current schema is production-ready and significantly better than typical legacy
+user databases. Most future improvements can be introduced **without breaking changes**.
+
+Primary future wins:
+
+* Redis-backed statistics
+* normalized roles and social platforms
+* hash-based media storage
+
+---
+
+**Status:** Approved for production
+**Next steps:** API design, public profile queries, legacy user migration
+
+```