my_openplace/CONTENT-MANAGEMENT.md

Site Content Management System

This document explains how to manage site content (modals, rules, etc.) using the new database-driven system.

Overview

The site content management system allows administrators to modify:

• Modal content (welcome modal, rules, instructions)
• Help text (paint faster, map lagging)
• Footer links and contact information
• Site title and branding
• Any other text content on the site

Content is stored in MySQL and can be edited through an admin interface, supporting multiple locales (English, Chinese, etc.).

Architecture

Database Schema

Table: SiteContent

• id: Auto-incrementing primary key
• key: Unique string identifier (e.g., modal.rules.title)
• value: Text content
• locale: Language code (en, zh, etc.)
• createdAt: Creation timestamp
• updatedAt: Last update timestamp

Backend API Endpoints

Public Endpoint:

• GET /api/site-content?locale=en - Fetch all content for a locale (used by frontend)

Admin Endpoints (require authentication & admin role):

• GET /api/admin/site-content - Get all content items
• POST /api/admin/site-content - Create or update a single item
• POST /api/admin/site-content/bulk - Bulk update multiple items
• DELETE /api/admin/site-content/:key - Delete an item
• POST /api/admin/site-content/initialize - Initialize default content

Frontend Integration

File: frontend/_app/info.js

• Automatically loads content from API on page load
• Falls back to hardcoded defaults if API fails
• Uses MutationObserver to patch modals when they appear
• Supports locale switching

Setup Instructions

1. Database Migration

Run the Prisma migration to create the SiteContent table:

pnpm db:push

2. Initialize Default Content

After the database is set up, initialize the default content by making a POST request:

curl -X POST http://localhost:3000/api/admin/site-content/initialize \
  -H "Cookie: j=YOUR_ADMIN_JWT_TOKEN"

Or use the admin UI (see below).

3. Access the Admin UI

Navigate to: http://localhost:3000/_app/admin-content-editor.html

Note: You must be logged in as an admin with a valid JWT token in cookies.

Using the Admin UI

Interface Features

1. Locale Selector - Switch between languages (en, zh)
2. Reload Button - Refresh content from database
3. Add New Item - Create new content entries
4. Initialize Defaults - Populate database with default content
5. Save All Changes - Bulk save modified items
6. Delete Button - Remove individual items

Content Keys

Content is organized using dot-notation keys:

Modal Content Keys

Overview Section:

• modal.overview.title - "Overview" heading
• modal.overview.videoUrl - YouTube embed URL

Paint Faster Section:

• modal.paintFaster.title - Section heading
• modal.paintFaster.mobile - Instructions for mobile users
• modal.paintFaster.desktop - Instructions for desktop users

Map Lagging Section:

• modal.mapLagging.title - Section heading
• modal.mapLagging.text - Help text
• modal.mapLagging.link - Link to hardware acceleration guide

Rules Section:

• modal.rules.title - "Rules" heading
• modal.rules.badge - Badge text (e.g., "Important")
• modal.rules.item.0 - First rule (with emoji)
• modal.rules.item.1 - Second rule
• modal.rules.item.N - Additional rules (add as needed)
• modal.rules.footer - Footer warning text

Footer Section:

• modal.footer.email - Contact email
• modal.footer.discord.url - Discord invite URL
• modal.footer.discord.text - Discord link text
• modal.footer.github.url - GitHub organization URL
• modal.footer.github.text - GitHub link text
• modal.footer.instagram.url - Instagram URL
• modal.footer.instagram.text - Instagram link text
• modal.footer.terms.url - Terms of service URL
• modal.footer.terms.text - Terms link text
• modal.footer.privacy.url - Privacy policy URL
• modal.footer.privacy.text - Privacy link text

Site-wide:

• site.title - Site title/branding

Adding New Rules

To add a new rule to the rules modal:

1. Click "Add New Item"
2. Set key to modal.rules.item.4 (or next available number)
3. Set value to 🚀 Your new rule text here
4. Click "Add Item"
5. Repeat for other locales (en, zh, etc.)

The frontend will automatically display all numbered rules in order.

Workflow Example

1. Login as admin to your FurryPlace instance
2. Navigate to /_app/admin-content-editor.html
3. Select locale (e.g., English)
4. Click "Initialize Defaults" (first time only)
5. Edit content directly in the text fields
6. Click "Save All Changes" to persist to database
7. Refresh your main site - changes appear immediately!

Development Notes

Adding New Content Fields

To add new editable content:

1. Choose a unique key (e.g., modal.newSection.title)
2. Add to the initialize defaults in src/routes/site-content.ts
3. Update the monkey patch in frontend/_app/info.js to use the new key
4. Add documentation to this file

Locale Support

Currently supports:

• en - English
• zh - Chinese

To add a new locale:

1. Add option to locale selector in admin UI
2. Initialize default content for that locale
3. Update frontend locale detection in info.js

Caching Considerations

• Frontend caches API response per page load
• No server-side caching (content always fresh from DB)
• Consider adding Redis/memory cache for production

Troubleshooting

Content Not Updating

1. Check browser console for [WPLACE_INFO] logs
2. Verify API endpoint returns data: GET /api/site-content?locale=en
3. Clear browser cache and reload
4. Check database for content entries: SELECT * FROM SiteContent;

Admin UI Not Loading

1. Verify you're logged in as admin
2. Check browser cookies for j JWT token
3. Verify role in User table is set to admin
4. Check browser console for authentication errors

Default Content Missing

Run initialization endpoint:

curl -X POST http://localhost:3000/api/admin/site-content/initialize \
  -H "Cookie: j=YOUR_JWT_TOKEN"

Security Notes

• Admin endpoints require authentication AND role='admin'
• Input validation prevents injection attacks
• Keys restricted to alphanumeric + dots + underscores
• No HTML rendering (XSS protection via text replacement)

Future Enhancements

• Add wysiwyg editor for formatted text
• Support for images/media uploads
• Version history and rollback
• Multi-tenant support (different content per domain)
• Import/export functionality (JSON/CSV)
• Preview changes before publishing
• Scheduled content changes
• Content approval workflow