# Product Updates CMS System Overview
**Last Updated**: 2025-11-20
**Status**: Production Ready ✅
## Executive Summary
The Product Updates CMS is a custom content management system built for Ordio to manage and display product feature announcements and improvements. It provides a password-protected admin interface for content creation and public-facing pages for displaying updates to website visitors.
## System Architecture
### High-Level Component Diagram
```
┌─────────────────────────────────────────────────────────────────┐
│ Product Updates CMS System │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Admin Panel │ │ Public Pages │ │ API Endpoints │
│ │ │ │ │ │
│ - Dashboard │ │ - Main Page │ │ - Upload │
│ - CRUD Ops │ │ - Month View │ │ - Image Proxy│
│ - Settings │ │ - Post View │ │ - Diagnostics│
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└───────────────────┼───────────────────┘
│
▼
┌────────────────────────┐
│ Storage Layer │
│ │
│ - JSON Data Store │
│ - Image Storage │
│ - Path Resolution │
└───────────────────────┘
```
### Core Components
#### 1. Admin Panel (`v2/pages/produkt_updates_admin.php`)
**Purpose**: Content management interface for marketing and customer success teams.
**Key Features**:
- Authentication system with session management
- Dashboard with insights, charts, and activity trends
- Month management (create, edit, delete)
- Feature management (big features with rich content)
- Improvement management (small improvements)
- Image upload and optimization
- Search and filtering
- Bulk operations
- Settings and storage status
**Technology Stack**:
- PHP backend with session-based authentication
- Alpine.js for reactive UI
- Chart.js for data visualization
- Quill.js for rich text editing
#### 2. Public Pages
**Main Listing Page** (`v2/pages/produkt_updates.php`):
- Displays current month's big features prominently
- Shows all small improvements chronologically
- Lists past months as archive links
- SEO-optimized with Schema.org markup
**Month Archive Page** (`v2/pages/produkt_updates_month.php`):
- Shows all updates for a specific month
- Displays month intro text
- Lists features and improvements for that month
**Individual Post Page** (`v2/pages/post.php`):
- Full-width hero image
- Rich content from `page_content` field
- Tag badges and platform icons
- Published date and navigation
**RSS Feed** (`v2/pages/produkt-updates-feed.xml.php`):
- RSS 2.0 format
- Includes all features and improvements
- Full content in CDATA sections
**XML Sitemap** (`v2/pages/sitemap-produkt-updates.xml.php`):
- Includes all pages
- Sets `lastmod` dates
- Priority and frequency settings
#### 3. API Endpoints
**Image Upload** (`v2/api/produkt-updates-upload.php`):
- Handles single and multiple file uploads
- Automatic image optimization (resize, compress, WebP conversion)
- Security validation (MIME type, size limits, dimensions)
- Returns optimized file paths
**Image Proxy** (`v2/api/serve-produkt-updates-image.php`):
- Serves images from filesystem locations
- Supports WebP auto-serving when browser supports it
- Rate limiting (100 requests/minute per IP)
- Caching headers (1 year cache, immutable)
**Diagnostics** (`v2/api/produkt-updates-diagnostics.php`):
- Checks PHP version and extensions
- Validates file system permissions
- Tests external resources (CDN libraries)
- Validates JSON data structure
**Storage Health** (`v2/api/produkt-updates-storage-health.php`):
- Quick health check for storage locations
- Reports data and image file locations
- Checks persistence status
- Returns JSON status
#### 4. Storage System
**SSOT** (`v2/config/produkt-updates-storage.php`, `v2/includes/produkt-updates-paths.php`):
- Single JSON path for read/write: `v2/data/produkt-updates/produkt_updates.json` (or `ORDIO_PRODUKT_UPDATES_ROOT`)
- Images: `v2/data/produkt-updates/images/` — public URL `/produkt-updates/bilder/{file}`
- Legacy `wp-content/uploads/produkt-updates/` read-only for images until migrated
- Atomic JSON writes: `v2/includes/produkt-updates-json.php`
**Data Storage**:
- **Canonical**: `{root}/produkt_updates.json`
**Image Storage**:
- **Canonical**: `{root}/images/`
## Data Flow
### Content Creation Flow
```
1. Admin logs in → Session authenticated
2. Admin creates/edits content → Form submission (POST)
3. Data validated and sanitized → PHP processing
4. JSON file updated → Atomic write operation
5. Success response → Admin redirected with confirmation
6. Public pages read updated data → Display new content
```
### Image Upload Flow
```
1. Admin selects images → File input
2. Images uploaded via AJAX → produkt-updates-upload.php
3. Images validated → MIME type, size, dimensions
4. Images optimized → Resize, compress, WebP conversion
5. Images saved to SSOT `images/` directory
6. Image paths returned → Stored in JSON data (canonical `/produkt-updates/bilder/…`)
7. Images served → produkt-updates-bilder.php (or legacy proxy)
```
### Public Page Rendering Flow
```
1. Visitor requests page → HTTP GET request
2. PHP loads JSON data → findReadableDataFile()
3. Data parsed and processed → Month/feature extraction
4. HTML generated → Template rendering
5. Images loaded → `/produkt-updates/bilder/` (or proxy for legacy URLs)
6. Page served to visitor → Complete HTML response
```
## File Structure
```
v2/
├── pages/
│ ├── produkt_updates_admin.php # Admin CMS interface
│ ├── produkt_updates.php # Main public listing page
│ ├── produkt_updates_month.php # Monthly archive page
│ ├── post.php # Individual post/feature page
│ ├── produkt-updates-feed.xml.php # RSS feed
│ └── sitemap-produkt-updates.xml.php # XML sitemap
├── includes/
│ └── produkt-updates-paths.php # Path resolution functions
├── api/
│ ├── produkt-updates-upload.php # Image upload handler
│ ├── serve-produkt-updates-image.php # Image proxy endpoint
│ ├── produkt-updates-diagnostics.php # Diagnostics endpoint
│ └── produkt-updates-storage-health.php # Health check endpoint
├── admin/produkt-updates/
│ ├── USER_GUIDE.md # User documentation
│ ├── CODE_DOCUMENTATION.md # Developer documentation
│ ├── discover-writable-directories.php # Directory discovery tool
│ ├── analyze-production-setup.php # Production analysis tool
│ ├── list-images.php # Image listing tool
│ └── migrate-missing-images.php # Image migration tool
├── config/
│ └── admin_config.php # Admin configuration (password hash)
├── helpers/
│ ├── storage-logger.php # Centralized storage logging
│ └── rate-limiter.php # Rate limiting helper
└── logs/
└── produkt-updates-storage.log # Storage operation logs
wp-content/
└── uploads/
└── produkt-updates/ # PRIMARY: Persistent storage
├── produkt_updates.json # JSON data store
└── [uploaded-images]/ # Uploaded images directory
```
## Data Structure
### JSON Schema (`produkt_updates.json`)
```json
{
"current_month": "november-2025",
"last_updated": "2025-11-20T10:30:00+00:00",
"settings": {
"max_big_features": 5,
"max_small_improvements": 10
},
"months": {
"november-2025": {
"month": "November 2025",
"slug": "november-2025",
"published_date": "2025-11-01",
"intro_text": "Brief description",
"page_title": "Optional *blue* markup",
"big_features": [
{
"id": "feature_123",
"number": 1,
"title": "Feature Title",
"description": "HTML content
",
"page_content": "Full HTML content
",
"read_more_link": "feature-slug",
"published_date": "2025-11-15",
"tag": "neues-feature",
"platforms": ["desktop", "mobile"],
"featured_image": "/v2/api/serve-produkt-updates-image.php?file=image.webp"
}
],
"small_improvements": [
{
"id": "improvement_456",
"number": 1,
"title": "Improvement Title",
"description": "HTML content
",
"published_date": "2025-11-20",
"platforms": ["desktop"],
"featured_image": "/v2/api/serve-produkt-updates-image.php?file=image2.webp"
}
]
}
}
}
```
## Key Design Decisions
### 1. JSON-Based Storage
**Why**: Simple, no database required, easy to version control, fast reads/writes.
**Trade-offs**:
- ✅ Simple implementation
- ✅ Easy to backup and restore
- ✅ No database dependencies
- ❌ Not ideal for very large datasets
- ❌ Single file bottleneck (mitigated by atomic writes)
### 2. WordPress Uploads Directory as Primary Storage
**Why**: Already writable on production, persistent across server restarts, familiar to developers.
**Trade-offs**:
- ✅ No SSH access required
- ✅ Persistent storage
- ✅ Standard WordPress location
- ❌ Requires WordPress to be installed
- ❌ Tied to WordPress structure
### 3. Image Proxy Endpoint
**Why**: Allows serving images from non-web-accessible directories, enables optimization, supports WebP auto-serving.
**Trade-offs**:
- ✅ Flexible storage locations
- ✅ Security (no direct file access)
- ✅ Optimization opportunities
- ❌ Additional server processing
- ❌ Requires PHP execution
### 4. Multi-Tier Fallback System
**Why**: Ensures system works even if primary storage isn't writable, graceful degradation.
**Trade-offs**:
- ✅ System always functional
- ✅ Automatic recovery
- ❌ Complexity in path resolution
- ❌ Potential for data inconsistency (mitigated by synchronization)
## Security Features
### Authentication
- Password-protected admin panel
- Session-based authentication
- Session timeout (30 minutes)
- Remember me functionality (30 days)
- Login attempt limiting (5 attempts, 15-minute lockout)
### Input Validation
- All user input sanitized
- HTML content sanitized (allowed tags only)
- File upload validation (MIME type, size, dimensions)
- Path traversal prevention
### Rate Limiting
- Image proxy: 100 requests/minute per IP
- Diagnostic endpoints: 10 requests/minute per IP
- Migration scripts: 1 request/5 minutes per session
### File Upload Security
- MIME type validation
- File size limits (5MB max)
- Dimension limits (4000x4000px max)
- Automatic image optimization removes embedded scripts
- Directory traversal prevention
## Performance Optimizations
### Image Optimization
- Automatic resizing to max 1920x1920px
- Compression (JPEG: 85 quality, PNG: level 6)
- WebP conversion when possible
- File size reduction: 30-70%
### Caching
- Images: 1 year cache, immutable
- JSON data: No cache (always fresh)
- Browser caching via ETag and Last-Modified headers
### Code Optimizations
- Single JSON file load per request
- Atomic file writes (temp file + rename)
- Lazy loading for images on public pages
- Minimal external dependencies
## Dependencies
### PHP Requirements
- PHP 7.4+
- JSON extension (required)
- GD extension (for image optimization)
- mbstring extension (with fallbacks if missing)
- Session support
### JavaScript Libraries (CDN)
- Alpine.js (reactive UI)
- Chart.js (data visualization)
- Quill.js (rich text editor)
### External Services
- None (fully self-contained)
## Related Documentation
- [Admin Panel Features](./PRODUCT_UPDATES_ADMIN_FEATURES.md) - Complete feature list
- [Public Pages](./PRODUCT_UPDATES_PUBLIC_PAGES.md) - Public page structure
- [API Reference](./PRODUCT_UPDATES_API_REFERENCE.md) - All API endpoints
- [Storage System](./PRODUCT_UPDATES_STORAGE.md) - Storage architecture
- [Development Guide](./PRODUCT_UPDATES_DEVELOPMENT_GUIDE.md) - How to extend the system
- [Troubleshooting](./PRODUCT_UPDATES_TROUBLESHOOTING.md) - Common issues and solutions
## Version History
- **2025-11-20**: Storage system updated to use WordPress uploads directory as primary persistent storage
- **2025-11-19**: Path resolution fixed to ensure images display correctly
- **2025-11-18**: Multi-tier fallback system implemented
- **2025-11-17**: Image proxy endpoint created
- **2025-11-16**: Initial system implementation