Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/1999azzar/lilyopencms

A comprehensive Flask-based content management system with advanced SEO features, multimedia management, and robust user permissions. Built for modern web publishing with automatic image optimization, comprehensive sitemap generation, and enterprise-grade security.
https://github.com/1999azzar/lilyopencms

cms-backend cms-experiment cms-framework python

Last synced: 7 days ago
JSON representation

A comprehensive Flask-based content management system with advanced SEO features, multimedia management, and robust user permissions. Built for modern web publishing with automatic image optimization, comprehensive sitemap generation, and enterprise-grade security.

Awesome Lists containing this project

README 

          
# LilyOpenCms - Modern Content Management System



A comprehensive Flask-based content management system with advanced SEO features, multimedia management, and robust user permissions. Built for modern web publishing with automatic image optimization, comprehensive sitemap generation, and enterprise-grade security.



## Features



### Recent System Improvements (2025-09-08)



- **✅ Aggressive Query Caching System**: Advanced caching with background refresh, smart preloading, and extended cache times

  - Background refresh system that refreshes cache at 80% of timeout

  - Smart preloading with prediction patterns for related queries

  - Extended cache times (2x) for aggressive mode performance

  - Preload queue system for background query execution

  - Cache warming functionality for common queries on startup

  - Enhanced statistics tracking (preloads, background refreshes, prediction accuracy)

  - Aggressive caching decorators: `@cache_frontend_critical`, `@cache_user_dashboard`, `@cache_public_content`, `@cache_navigation_data`

  - Applied to all major route files for maximum performance impact

  - Thread-safe cache operations with proper locking

  - Smart cache invalidation with pattern matching

- **✅ SSR Optimization Dashboard**: Live refresh functionality with dynamic DOM updates

  - Read-only endpoints for SSR statistics and cache stats

  - Settings endpoints for template caching configuration

  - Dynamic DOM updates without full page reload

  - Settings persistence to `instance/app_settings.json`

- **✅ Comment Edit & Delete System**: Comprehensive comment management with inline editing and deletion in user library

- **✅ User Image Management**: Dedicated image management page with upload, edit, delete, and visibility controls

- **✅ Enhanced Profile Layout**: Optimized profile.html to use more viewport width with improved spacing and layout

- **✅ Content Deletion Request System**: Role-based content deletion with admin approval workflow for news and albums

- **✅ SQLAlchemy Relationship Fixes**: Fixed User.news and User.albums relationships with explicit foreign_keys

- **✅ Content Deletion Management UI**: Admin interface for managing content deletion requests with bulk operations

- **✅ Enhanced Content Security**: Only admin-tier users can delete content directly, others must request approval

- **✅ Smart Routing System**: Role-based dashboard routing (admin/superuser/owner → `/settings`, general users → `/dashboard`)

- **✅ Template Context Integration**: Added `get_user_dashboard_url()` function to Flask template context processors

- **✅ Consistent Navigation Experience**: All dashboard links now use smart routing for seamless navigation

- **✅ Enhanced User Management System**: Advanced user listing with pagination, search, and filtering

- **✅ User Creation API**: Admin user creation with role assignment and premium status

- **✅ User Statistics Dashboard**: Real-time user statistics and role distribution

- **✅ Backup API Endpoints**: Resolved 404 errors for roles and permissions

- **✅ Permission Management**: Centralized permission system with 80+ granular permissions

- **✅ Admin Sidebar Enhancement**: Sub-group navigation with permission-based visibility

- **✅ Comprehensive Endpoint Testing**: 95% success rate with full authentication testing

- **✅ Template Path Fixes**: All admin template paths corrected and verified

- **✅ Authentication Enhancement**: Session-based testing with proper CSRF token handling

- **✅ Error Handling**: Robust error handling and fallback mechanisms implemented

- **✅ DOCX Upload Tool Enhancement**: Added quick link to news management for seamless workflow integration



### Content Management



- **Advanced News Management**: Create, edit, delete articles with rich text editing (edit via `/settings/create_news?news_id=`, redirects back to `/settings/manage_news` or album chapters if `album_id` present)

- **Album Management System**: Create albums containing multiple news/articles as chapters, like a novel structure

- **Public Album Pages**: Dedicated album listing, detail pages, and chapter reader with markdown support

- **Related Content Discovery**: Related albums carousel and author's other works sections

- **Comment System**: Nested comments with like/dislike functionality, moderation, spam detection, and reporting system

- **Rating System**: 5-star rating system with statistics, analytics, and distribution tracking for news and albums

- **SEO Optimization**: Per-article SEO management (meta descriptions, keywords, Open Graph tags, Twitter Cards, Schema Markup)

- **Content Scheduling**: Schedule posts for future publication

- **Bulk Operations**: Mass edit, delete, and categorize content

- **Content Archiving**: Archive old content while preserving access

- **Content Duplication**: Clone articles for quick content creation

- **Revision History**: Track changes and restore previous versions

- **Related Articles**: Smart content suggestions

- **Enhanced Settings Management**: Advanced admin dashboard with tabbed interface, real-time search, and optimized JavaScript architecture



### Media Management



- **Automatic Image Optimization**: WebP conversion, compression, and multiple thumbnail sizes

- **User Image Management**: Dedicated image management page with upload, edit, delete, and visibility controls

- **Image Visibility Control**: Toggle image visibility with proper permission checks

- **Image Gallery Integration**: Seamless integration with content creation workflows

- **YouTube Integration**: Embed and manage YouTube videos

- **Gallery Management**: Organize and display image collections

- **Media Usage Tracking**: See which images are used where

- **Bulk Upload**: Multiple file upload with progress tracking

- **CDN Ready**: Optimized for content delivery networks



### User & Permission System



- **Smart Routing System**: Role-based dashboard routing (admin/superuser/owner → `/settings`, general users → `/dashboard`)

- **Template Context Integration**: Automatic dashboard selection based on user role

- **Enhanced User Management**: Advanced user listing with pagination, search, and filtering

- **User Creation System**: Admin user creation with role assignment and premium status

- **User Statistics Dashboard**: Real-time user statistics and role distribution

- **Custom Role System**: Beyond basic admin/general roles with 14 custom roles

- **Granular Permissions**: Matrix-based access control with 80+ granular permissions

- **Centralized Permission System**: Permission management with role-based inheritance

- **User Activity Tracking**: Login history, content creation, admin actions

- **Account Management**: Profile pictures, bios, social links

- **User Performance Metrics**: Track user contributions and activity

- **Account Suspension**: Temporary and permanent account restrictions

- **Registration Approval**: Admin-controlled user registration

- **Backup API Endpoints**: Resolved 404 errors for roles and permissions



### SEO & Analytics



- **SEO Leveling System**: Hierarchical SEO management with content-specific SEO taking precedence over root SEO

- **Comprehensive Sitemaps**: XML sitemaps for all content types

- **SEO Score Calculation**: Automated SEO scoring (0-100)

- **Meta Tag Management**: Complete meta tag control

- **Schema Markup**: JSON-LD structured data generation

- **Social Media Optimization**: Open Graph and Twitter Card support

- **Analytics Dashboard**: Content performance metrics

- **Search Engine Optimization**: URL slugs, canonical URLs, robots.txt



### Security & Performance



- **Advanced Security**: Rate limiting, input validation, CSRF protection

- **File Upload Security**: Virus scanning, type restrictions

- **Session Management**: Secure session handling with auto-logout

- **Database Security**: SQL injection protection with parameterized queries

- **Aggressive Query Caching**: Advanced caching system with background refresh, smart preloading, and extended cache times

- **Performance Optimization**: Redis caching, database optimization, lazy loading, progressive images, externalized JavaScript modules

- **Performance Monitoring**: Real-time metrics, slow query detection, cache management

- **Frontend Optimization**: Externalized JavaScript files for better caching and faster loading

- **Cache Statistics**: Comprehensive cache performance tracking with preloads, background refreshes, and prediction accuracy



### Premium & Subscription System



- **Premium Content**: Exclusive content for subscribers

- **Subscription Management**: Multiple subscription tiers

- **Ad-Free Experience**: Premium users get ad-free browsing

- **Content Gating**: Protect premium content with subscription requirements

- **Payment Integration**: Ready for payment gateway integration



### Content Deletion Request System



- **Consistent Workflow**: All users (including admins) must request content deletion for approval

- **Request Workflow**: Any user can request deletion of any content for admin approval

- **Admin Approval**: Content moderators and admins approve/reject deletion requests

- **Bulk Operations**: Efficient bulk approve/reject functionality for multiple requests

- **Request Management**: Dedicated admin interface for managing deletion requests

- **Audit Trail**: Complete tracking of who requested, when, and approval status

- **Enhanced Security**: Prevents unauthorized content deletion while maintaining consistent workflownn### 🌐 Public API Endpointsn- **Multiplatform Access**: JSON endpoints for mobile apps, desktop clients, and third-party integrationsn- **News API**: Public endpoints for news articles and lists with filtering and paginationn- **Albums API**: Public endpoints for albums, chapters, and related contentn- **User Profiles API**: Public user profile data, statistics, and library accessn- **Categories & Tags API**: Public access to content categories and tag systemn- **Comments API**: Public comment retrieval with threading and moderationn- **Unified Search API**: Cross-content search with type filtering and paginationn- **No Authentication Required**: All endpoints are publicly accessible for multiplatform usage



### Comment & Rating System



- **Nested Comments**: Threaded comment system with replies

- **Inline Comment Editing**: Edit comments directly in the user library with real-time updates

- **Comment Deletion**: Delete comments with confirmation dialogs and DOM updates

- **Like/Dislike System**: Users can like or dislike comments

- **Comment Moderation**: Admin approval system with spam detection

- **Comment Reporting**: Users can report inappropriate comments

- **Spam Detection**: Automatic spam filtering with configurable rules

- **User Library Integration**: Comment management in user library with edit/delete capabilities

- **5-Star Rating System**: Rate news articles and albums (1-5 stars)

- **Rating Statistics**: Average ratings, distribution, and analytics

- **Rating Analytics**: Comprehensive rating dashboard for admins

- **User Rating History**: Track all ratings by specific users

- **Content Rating Protection**: Prevent duplicate ratings per user

- **Rating Distribution**: Visual breakdown of 1-5 star ratings

- **Top Rated Content**: Discover highest-rated articles and albums



### Achievement System



- **Comprehensive Gamification**: Track user activities and award achievements

- **Streak Tracking**: Login, activity, and reading streaks with daily consistency

- **Contribution Achievements**: Content creation milestones (articles, albums, images)

- **Exploration Achievements**: Content engagement (comments, ratings, reading)

- **Community Achievements**: Social interactions (likes, comments received)

- **Milestone Achievements**: Level progression and point accumulation

- **Points & Leveling**: Point-based progression system with automatic level-ups

- **Achievement Categories**: Organized into 7 categories with visual indicators

- **Progress Tracking**: Detailed progress history and completion rates

- **Real-time Notifications**: Instant achievement unlock notifications

- **Achievement Dashboard**: Comprehensive user achievement overview

- **Performance Optimized**: Efficient tracking with database indexes and cleanup



## Tech Stack



### Backend



- **Python 3.8+** - Core programming language

- **Flask 2.x** - Web framework

- **SQLAlchemy** - ORM and database management

- **Safe Migration System** - Custom database migration system

- **Flask-Login** - Authentication system

- **Flask-WTF** - Form handling and CSRF protection

- **Pillow (PIL)** - Image processing and optimization



### Frontend



- **Tailwind CSS** - Utility-first CSS framework

- **JavaScript (ES6+)** - Modern JavaScript with externalized modules for optimal caching

- **SimpleMDE** - Markdown editor

- **Swiper.js** - Touch slider for featured content

- **Advanced Search System** - Real-time search with dedicated results tab and highlighted matches



### Database



- **SQLite** - Default database (production-ready alternatives supported)

- **PostgreSQL/MySQL** - Production database options



### Deployment



- **Gunicorn** - WSGI server

- **Passenger** - Alternative WSGI server

- **Docker** - Containerization ready



## Installation



### Prerequisites



- Python 3.8 or higher

- pip package manager

- Git

- Redis (for performance optimizations)



### Quick Start



1. **Clone the repository**



   ```bash

   git clone 

   cd LilyOpenCms

   ```

2. **Create virtual environment**



   ```bash

   python -m venv .venv

   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

   ```

3. **Install dependencies**



   ```bash

   pip install -r requirements.txt

   ```

4. **Set up Redis (Required for performance optimizations)**



   **Ubuntu/Debian:**



   ```bash

   sudo apt update

   sudo apt install redis-server

   sudo systemctl start redis-server

   sudo systemctl enable redis-server

   ```



   **macOS:**



   ```bash

   brew install redis

   brew services start redis

   ```



   **Windows:**



   ```bash

   # Download from https://redis.io/download

   # Or use WSL2 with Ubuntu instructions above

   ```



   **Using the provided setup script:**



   ```bash

   chmod +x optimizations/setup_redis.sh

   ./optimizations/setup_redis.sh

   ```

5. **Set up environment variables**



   ```bash

   cp .env.example .env

   # Edit .env with your configuration

   ```

6. **Initialize database**



   ```bash

   flask db upgrade

   ```

7. **Seed initial data (optional)**



   ```bash

   cd helper

   python generate_user.py

   python add_chategories.py

   python add_fake_news.py

   python add_fake_images.py

   python add_videos.py

   python init_footer_data.py

   ```

8. **Set up achievement system (optional)**



   ```bash

   # Initialize achievement system with default categories and achievements

   python helper/init_achievement_system.py



   # Test the achievement system

   python test/test_achievement_system.py

   ```

9. **Run the application**



   ```bash

   python main.py

   ```



   Open `http://127.0.0.1:5000` in your browser.



### Redis Configuration



The application uses Redis for caching and performance optimizations. Make sure Redis is running before starting the application.



**Verify Redis is running:**



```bash

redis-cli ping

# Should return: PONG

```



**Test Redis connection from Python:**



```bash

python -c "import redis; r = redis.Redis(); print('Redis connection:', r.ping())"

```



**Redis Configuration Options:**



- **Default**: `redis://localhost:6379/0`

- **With Password**: `redis://:password@localhost:6379/0`

- **Custom Host/Port**: Set `REDIS_HOST` and `REDIS_PORT` in `.env`



## Documentation



### Core Documentation



- **[Documentation Index](docs/README.md)** - Complete documentation index and navigation

- **[API Documentation](docs/api.md)** - Complete API reference with endpoints and examples

- **[Admin UI Guide](docs/admin_ui.md)** - Comprehensive admin interface documentation

- **[Sitemap Documentation](docs/SITEMAP_DOCUMENTATION.md)** - Complete sitemap system guide

- **[Development Roadmap](docs/TODO.md)** - Current development status and progress tracking

- **[Achievement System Guide](docs/ACHIEVEMENT_SYSTEM_GUIDE.md)** - Comprehensive achievement system documentation



### Performance & Optimization



- **[Performance & Optimizations – Comprehensive](docs/PERFORMANCE_OPTIMIZATIONS_COMPREHENSIVE.md)** - Complete performance guide with quick start and advanced topics

- **[Performance Optimization Guide](docs/PERFORMANCE_OPTIMIZATION.md)** - Comprehensive performance optimization

- **[Performance Quick Start](docs/PERFORMANCE_QUICK_START.md)** - Quick setup for performance features

- **[Advanced Optimizations](docs/ADVANCED_OPTIMIZATIONS.md)** - Advanced optimization techniques

- **[Optimization Reorganization](docs/OPTIMIZATION_REORGANIZATION.md)** - Optimization system structure



### System Implementation



- **[Current System Status](docs/CURRENT_SYSTEM_STATUS.md)** - Current implementation status overview

- **[Implementation Summary](docs/IMPLEMENTATION_SUMMARY.md)** - Current system implementation status

- **[Final Implementation Summary](docs/FINAL_IMPLEMENTATION_SUMMARY.md)** - Complete implementation overview

- **[Premium System Implementation](docs/PREMIUM_SYSTEM_IMPLEMENTATION.md)** - Premium content system guide

- **[Premium Content & Subscription – Comprehensive](docs/PREMIUM_SYSTEM_COMPREHENSIVE.md)** - Premium content and subscription system

- **[Subscription System Status](docs/SUBSCRIPTION_SYSTEM_STATUS.md)** - Subscription feature status

- **[Comment & Rating System – Comprehensive](docs/COMMENT_RATING_COMPREHENSIVE.md)** - Complete comment and rating system documentation

- **[Comment Rating System](docs/COMMENT_RATING_SYSTEM.md)** - Comment and rating system documentation

- **[Premium Content System](docs/PREMIUM_CONTENT_SYSTEM.md)** - Premium content and subscription features

- **[Weighted Rating System](docs/WEIGHTED_RATING_SYSTEM.md)** - Advanced rating algorithms and analytics

- **[Unified News System](docs/UNIFIED_NEWS_SYSTEM.md)** - News and article management system

- **[Contact Details Guide](docs/CONTACT_DETAILS_GUIDE.md)** - Contact information management

- **[SEO Leveling System](docs/seo_leveling_system.md)** - Hierarchical SEO management with content-specific overrides

- **[SEO Leveling Comprehensive](docs/SEO_LEVELING_COMPREHENSIVE.md)** - Hierarchical SEO management system



### UI/UX & Design



- **[Card Design System](docs/CARD_DESIGN_SYSTEM.md)** - Complete card design system with 4 distinct designs

- **[Card Design Troubleshooting](docs/CARD_DESIGN_TROUBLESHOOTING.md)** - Troubleshooting guide for card design issues



### Ads & Marketing



- **[Ads Injection System – Comprehensive](docs/ADS_INJECTION_COMPREHENSIVE.md)** - Ads injection architecture and roadmap



### Content & Media



- **[Album View Count Implementation](docs/ALBUM_VIEW_COUNT_IMPLEMENTATION.md)** - View count tracking for albums

- **[Share System Fix](docs/SHARE_SYSTEM_FIX.md)** - Social sharing system implementation



### Deployment & Configuration



- **[Deployment Guide](docs/DEPLOYMENT_GUIDE.md)** - Complete deployment guide for DirectAdmin hosting and other environments



## SEO Leveling System



The SEO Leveling System implements a hierarchical approach to SEO data management, ensuring that content-specific SEO takes precedence over root SEO settings. This prevents the root SEO from always taking over and allows for proper content-specific optimization.



### Key Features



- **Hierarchical SEO Management**: Content-specific SEO takes precedence over root SEO

- **URL Pattern Detection**: Automatic detection of news articles (`/news//`) and albums (`/album//`)

- **Content-Specific Overrides**: News and album SEO fields override root SEO settings

- **Template Integration**: Updated `base.html` to use unified `seo_data` structure

- **SEO Override Blocks**: Enhanced `reader.html` and `album_detail.html` with content-specific SEO blocks

- **Proper OG Types**: Articles use `og:type=article`, albums use `og:type=book`

- **Fallback System**: Root SEO provides sensible defaults when content-specific SEO is not available



### SEO Hierarchy (Priority Order)



1. **Content-Specific SEO** (Highest Priority)



   - News/Article SEO

   - Album SEO

   - Chapter SEO

2. **Root SEO** (Fallback)



   - Page-specific root SEO settings

   - Default values

3. **Brand Defaults** (Lowest Priority)



   - Brand identity settings

   - Hardcoded fallbacks



### Implementation Details



- **Context Processor**: `inject_seo_data()` handles SEO leveling logic

- **URL Detection**: Automatic detection of content types based on URL patterns

- **Template Blocks**: Content templates can override SEO data using template blocks

- **Backward Compatibility**: Existing SEO functionality remains unchanged

- **Performance Optimized**: Efficient SEO data retrieval and caching



For detailed implementation information, see [SEO Leveling System Documentation](docs/seo_leveling_system.md).



### Development



- **[Development Roadmap](docs/TODO.md)** - Current development status and future plans

- **[Helper Scripts README](helper/README.md)** - Helper scripts documentation and usage

- **[Routes Utils README](routes/utils/README.md)** - Permission and role management system documentation



## Configuration



### Environment Variables



Create a `.env` file in the root directory:



```env

# Flask Configuration

SECRET_KEY=your-secret-key-here

FLASK_ENV=development

FLASK_DEBUG=True



# Database Configuration

DATABASE_URI=sqlite:///instance/LilyOpenCms.db



# File Upload Configuration

MAX_CONTENT_LENGTH=16777216  # 16MB max file size

UPLOAD_FOLDER=static/uploads



# Email Configuration (optional)

MAIL_SERVER=smtp.gmail.com

MAIL_PORT=587

MAIL_USE_TLS=True

MAIL_USERNAME=your-email@gmail.com

MAIL_PASSWORD=your-app-password



# YouTube API (optional)

YOUTUBE_API_KEY=your-youtube-api-key



# External Services (optional)

GOOGLE_ANALYTICS_ID=GA-XXXXXXXXX-X



# Performance Optimization (optional)

REDIS_URL=redis://localhost:6379/0

REDIS_HOST=localhost

REDIS_PORT=6379

REDIS_PASSWORD=

```



## Performance Optimizations



LilyOpenCms includes comprehensive performance optimizations organized in the `optimizations/` package:



### Quick Setup



```bash

# Install Redis and configure performance optimizations

chmod +x optimizations/setup_redis.sh

./optimizations/setup_redis.sh



# Access performance dashboard

# Visit: http://localhost:5000/admin/performance

```



### Key Features



- **Aggressive Query Caching**: Advanced caching system with background refresh, smart preloading, and extended cache times

- **Redis Caching**: Fast data retrieval with intelligent cache invalidation

- **Database Optimization**: Connection pooling, query optimization, automatic indexing

- **Frontend Optimization**: Lazy loading, progressive images, asset optimization, externalized JavaScript modules

- **Performance Monitoring**: Real-time metrics, slow query detection, cache management

- **JavaScript Optimization**: Externalized modules for better caching and faster loading times

- **Cache Statistics**: Comprehensive performance tracking with preloads, background refreshes, and prediction accuracy



### Documentation



- [Performance Optimization Guide](docs/PERFORMANCE_OPTIMIZATION.md)

- [Quick Start Guide](docs/PERFORMANCE_QUICK_START.md)

- [Advanced Optimizations](docs/ADVANCED_OPTIMIZATIONS.md)

- [Optimizations Package README](optimizations/README.md)



## API Endpoints



### Content Management



- `GET /api/news` - List news articles with filtering

- `POST /api/news` - Create new article

- `PUT /api/news/` - Update article

- `DELETE /api/news/` - Delete article (admin-tier users only)

- `POST /api/news//request-deletion` - Request article deletion (non-admin users)

- `GET /api/news/deletion-requests` - Get news deletion requests (admin only)

- `POST /api/news//approve-deletion` - Approve news deletion request (admin only)

- `POST /api/news//reject-deletion` - Reject news deletion request (admin only)

- `PATCH /api/news//visibility` - Toggle visibility

- `PATCH /api/news//archive` - Archive article

- `PATCH /api/news//unarchive` - Unarchive article

- `POST /api/news//duplicate` - Duplicate article

- `GET /api/albums` - List albums with filtering

- `POST /api/albums` - Create new album

- `PUT /api/albums/` - Update album

- `DELETE /api/albums/` - Delete album (admin-tier users only)

- `POST /admin/albums//request-deletion` - Request album deletion (non-admin users)

- `GET /admin/albums/deletion-requests` - Get album deletion requests (admin only)

- `POST /admin/albums//approve-deletion` - Approve album deletion request (admin only)

- `POST /admin/albums//reject-deletion` - Reject album deletion request (admin only)

- `PATCH /api/albums//visibility` - Toggle album visibility

- `PATCH /api/albums//archive` - Archive album

- `PATCH /api/albums//unarchive` - Unarchive album

- `POST /api/albums//chapters` - Add chapter to album

- `DELETE /api/albums//chapters/` - Remove chapter from album



### Comment System



- `GET /api/comments//` - Get comments for news/album with pagination

- `POST /api/comments` - Create new comment (requires authentication)

- `PUT /api/comments/` - Update comment with success response (owner or admin only)

- `DELETE /api/comments/` - Delete comment with success response (owner or admin only)

- `GET /api/account/library/comments` - Get user's library comments with edit/delete capabilities

- `POST /api/comments//like` - Like/unlike comment

- `POST /api/comments//report` - Report comment for moderation

- `GET /admin/comments` - Admin comment moderation interface

- `POST /admin/comments//approve` - Approve comment (admin only)

- `POST /admin/comments//reject` - Reject comment (admin only)

- `POST /admin/comments//mark-spam` - Mark comment as spam (admin only)

- `POST /admin/comments//delete` - Admin delete comment



### Rating System



- `GET /api/ratings//` - Get rating statistics for news/album

- `POST /api/ratings` - Create or update rating (requires authentication)

- `DELETE /api/ratings//` - Delete user's rating

- `GET /api/ratings/stats` - Get overall rating statistics

- `GET /api/ratings/user/` - Get all ratings by specific user

- `GET /admin/ratings` - Admin rating management interface

- `POST /admin/ratings//delete` - Admin delete rating

- `GET /admin/ratings/analytics` - Admin rating analytics dashboard



### Public Album Pages



- `GET /albums` - Public album listing page with filtering and search

- `GET /album//` - Album detail page with author info and chapters

- `GET /album//chapter//` - Chapter reader with markdown support



### Media Management



- `GET /api/images` - List images with filtering

- `POST /api/images` - Upload image

- `PUT /api/images/` - Update image

- `DELETE /api/images/` - Delete image

- `PATCH /api/images//visibility` - Toggle image visibility

- `GET /user//images` - User image management page

- `POST /user//images/upload` - Upload image to user gallery

- `PUT /user//images//update` - Update user image

- `DELETE /user//images//delete` - Delete user image

- `GET /api/youtube_videos` - List YouTube videos

- `POST /api/youtube_videos` - Add YouTube video

- `PUT /api/youtube_videos/` - Update video

- `DELETE /api/youtube_videos/` - Delete video



### User Management



- `GET /api/users` - List users with pagination, search, and filtering (role, status, verification)

- `POST /api/users` - Create user with role assignment and premium status

- `GET /api/users//details` - Get comprehensive user details and statistics

- `POST /api/users//reset-password` - Reset user password (admin only)

- `GET /api/users/stats` - Get overall user statistics and role distribution

- `GET /api/pending/stats` - Get pending registration statistics

- `PUT /api/users/` - Update user

- `DELETE /api/users/` - Delete user

- `PATCH /api/users//verify` - Toggle user verification

- `PATCH /api/users//status` - Toggle user status

- `POST /api/users//suspend` - Suspend user

- `POST /api/users//unsuspend` - Unsuspend user

- `GET /api/registrations/pending` - Get pending registrations

- `POST /api/registrations//approve` - Approve registration

- `POST /api/registrations//reject` - Reject registration

- `POST /api/user/request-account-deletion` - Request account deletion (general users only)

- `GET /api/users/deletion-requests` - Get account deletion requests (admin only)

- `POST /api/users//approve-deletion` - Approve account deletion request (admin only)

- `POST /api/users//reject-deletion` - Reject account deletion request (admin only)



### Roles & Permissions



- `GET /api/roles` - List roles (backup implementation in routes_users.py)

- `POST /api/roles` - Create role

- `PUT /api/roles/` - Update role

- `DELETE /api/roles/` - Delete role

- `GET /api/permissions` - List permissions (backup implementation in routes_users.py)

- `POST /api/permissions` - Create permission

- `PUT /api/permissions/` - Update permission

- `DELETE /api/permissions/` - Delete permission



### Navigation Management



- `GET /api/navigation-links` - List navigation links

- `POST /api/navigation-links` - Create navigation link

- `PUT /api/navigation-links/` - Update navigation link

- `DELETE /api/navigation-links/` - Delete navigation link

- `POST /api/navigation-links/bulk-update` - Bulk update navigation links



### SEO & Analytics



- `GET /sitemap.xml` - Main sitemap

- `GET /sitemap-news.xml` - News-specific sitemap

- `GET /sitemap-index.xml` - Sitemap index

- `GET /robots.txt` - Search engine directives

- `GET /api/analytics/visitors` - Visitor statistics

- `GET /api/analytics/content` - Content analytics

- `GET /api/analytics/activity` - Activity logs

- `GET /api/analytics/performance` - Performance metrics



### Premium & Subscription



- `GET /api/subscriptions/plans` - Get subscription plans

- `POST /api/subscriptions/create` - Create subscription

- `POST /api/subscriptions/cancel` - Cancel subscription

- `GET /api/subscriptions/status` - Get subscription status

- `POST /api/subscriptions/update-ad-preferences` - Update ad preferences

- `GET /api/subscriptions/check-premium-access` - Check premium access



## Authentication & Authorization



### User Roles



- **SUPERUSER**: Full system access with all permissions

- **ADMIN**: Content and user management with limited system access

- **GENERAL**: Basic content creation and personal management



### Smart Routing System



- **Role-Based Navigation**: Automatic dashboard routing based on user role

- **Admin/Superuser/Owner**: Redirected to `/settings` (admin dashboard)

- **General Users**: Redirected to `/dashboard` (reader dashboard)

- **Template Integration**: All dashboard links use smart routing via `get_user_dashboard_url()` function

- **Login Integration**: Login redirects use the same smart routing logic

- **Consistent Experience**: Seamless navigation across all templates



### Permission System



- **Enhanced User Management**: Advanced user listing with pagination, search, and filtering

- **User Creation System**: Admin user creation with role assignment and premium status

- **User Statistics Dashboard**: Real-time user statistics and role distribution

- **Granular Permissions**: Matrix-based access control with 80+ granular permissions

- **Centralized Permission System**: Permission management with role-based inheritance

- **Role-based Access**: Automatic permission assignment based on roles

- **Activity Logging**: Comprehensive audit trails for all actions

- **Session Management**: Secure session handling with auto-logout

- **Comprehensive Testing**: All endpoints tested with different user roles

- **Template Path Verification**: All admin templates properly configured

- **Error Handling**: Robust error handling for permission violations

- **Backup API Endpoints**: Resolved 404 errors for roles and permissions



## SEO Features



### Sitemap Generation



- **Main Sitemap**: All content types with proper priorities

- **News Sitemap**: News-specific optimization with publication dates

- **Sitemap Index**: For large sites with multiple sitemaps

- **SEO Integration**: Uses meta_robots, seo_slug, priorities, and changefreq



### SEO Management



- **Meta Tags**: Description, keywords, author, language, robots

- **Open Graph**: Social media optimization for Facebook, LinkedIn

- **Twitter Cards**: Twitter-specific optimization

- **Schema Markup**: JSON-LD structured data for search engines

- **SEO Scoring**: Automated SEO analysis (0-100 scale)

- **Canonical URLs**: Prevent duplicate content issues

- **URL Optimization**: SEO-friendly slugs and redirects



## UI/UX Features



### Design System



- **Tailwind CSS**: Utility-first styling with custom configuration

- **Responsive Design**: Mobile-first approach with breakpoint optimization

- **Dark Mode**: Theme switching capability with persistent preferences

- **Toast Notifications**: User feedback system with multiple types

- **Loading States**: Comprehensive loading indicators and skeleton screens



### Components



- **Dynamic Sidebar**: Role-based navigation with collapsible sections

- **Pagination**: Efficient content browsing with configurable page sizes

- **Search & Filter**: Advanced content discovery with multiple filters and real-time search results

- **Bulk Operations**: Efficient content management with batch processing

- **Modal System**: Reusable modal components for forms and confirmations

- **Data Tables**: Sortable, filterable tables with bulk actions

- **Tabbed Interfaces**: Advanced tabbed navigation with search integration and state management



## Database Models



### Core Models



- **User**: Authentication, profiles, roles, permissions, activity tracking

- **News**: Articles with SEO, scheduling, archiving, related content

- **Album**: Album management with chapters, completion status, hiatus tracking, author relationships

- **AlbumChapter**: Chapter relationships between albums and news articles

- **Category**: Content organization with hierarchical structure

- **Image**: Media management with optimization, usage tracking

- **YouTubeVideo**: Video content with metadata and embedding

- **TeamMember**: Team management with roles and contact information



### Comment & Rating Models



- **Comment**: User comments on news/albums with moderation, spam detection, nested replies

- **CommentLike**: Like/dislike system for comments with user tracking

- **CommentReport**: Comment reporting system for inappropriate content

- **Rating**: 5-star rating system for news/albums with statistics and analytics



### SEO & Brand Models



- **BrandIdentity**: Brand assets, colors, typography, guidelines

- **SocialMedia**: Social media links and platform management

- **ContactDetail**: Contact information and location data

- **NavigationLink**: Navigation menu management with internal/external links



### Legal & Policy Models



- **PrivacyPolicy**: Privacy policy content and versioning

- **MediaGuideline**: Media guidelines and usage policies

- **VisiMisi**: Vision and mission statements

- **Penyangkalan**: Disclaimer and legal disclaimers

- **PedomanHak**: Rights and guidelines documentation



### System Models



- **UserRole**: Role definitions and permissions

- **Permission**: Granular permission system

- **CustomRole**: Custom role creation and management

- **UserActivity**: Activity logging and audit trails

- **ShareLog**: Social sharing tracking and analytics



## Deployment



### Development



```bash

python main.py

```



### Production with Gunicorn



```bash

gunicorn --bind 0.0.0.0:8000 main:app

```



### Production with Passenger



```bash

# Configure passenger_wsgi.py

passenger start

```



### Docker Deployment



```dockerfile

FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["gunicorn", "--bind", "0.0.0.0:8000", "main:app"]

```



## Testing



### Running Tests



```bash

# Install dependencies

pip install -r requirements.txt



# Run all tests

python test/run_tests.py



# Run quick tests

python test/quick_test.py



# Run comprehensive endpoint tests (NEW)

python test/test_comprehensive_endpoints.py



# Run specific tests

python test/test_seo_leveling.py

python test/test_authentication.py

python test/test_user_management.py

```



### Test Coverage



- **Core System Tests**: Authentication, user management, database models

- **Performance Tests**: Monitoring, caching, optimization

- **Feature Tests**: Comments, ratings, assets, navigation

- **SEO Tests**: SEO leveling system, content-specific SEO overrides

- **Infrastructure Tests**: Redis connection, subscription system

- **Comprehensive Endpoint Tests**: Full endpoint testing with different user roles (no login, general, admin, superuser)

- **Authentication & Authorization Tests**: Session-based testing with proper CSRF token handling

- **Template Path Tests**: Verification of all admin template paths and rendering

- **Permission System Tests**: Role-based access control verification across all endpoints



### SEO Leveling Test



The SEO leveling system includes comprehensive tests to verify:



- ✅ Content-specific SEO takes precedence over root SEO

- ✅ URL pattern detection for news and album pages

- ✅ Template integration with SEO override blocks

- ✅ Proper OG types (article for news, book for albums)

- ✅ Fallback system with root SEO and brand defaults



```bash

# Run SEO leveling test specifically

python test/test_seo_leveling.py

```



### Comprehensive Endpoint Testing (NEW)



The system includes comprehensive endpoint testing with session-based authentication:



- ✅ **95% Success Rate**: 28/30 endpoints working correctly

- ✅ **Authentication Testing**: All user roles (general, admin, superuser) tested

- ✅ **Permission System**: Role-based access control verified

- ✅ **Template Paths**: All admin template paths fixed and verified

- ✅ **Session Management**: Proper CSRF token handling and session management

- ✅ **Error Handling**: Comprehensive error handling and fallback mechanisms



**Test Coverage:**



- Comment moderation endpoints

- Rating management endpoints

- Ads management endpoints

- Analytics endpoints

- User management endpoints

- Subscription endpoints

- SEO management endpoints



```bash

# Run comprehensive endpoint tests

python test/test_comprehensive_endpoints.py

```



## Contributing



1. Fork the repository

2. Create a feature branch (`git checkout -b feature/amazing-feature`)

3. Commit your changes (`git commit -m 'Add amazing feature'`)

4. Push to the branch (`git push origin feature/amazing-feature`)

5. Open a Pull Request



### Development Guidelines



- Follow PEP 8 Python style guide

- Write tests for new features

- Update documentation for API changes

- Use conventional commit messages

- Ensure all tests pass before submitting PR



## License



This project is licensed under the CC0 License - see the [LICENSE](LICENSE) file for details.



## Support



- **Documentation**: Check the [docs/](docs/) folder for comprehensive guides

- **Issues**: Report bugs via GitHub Issues

- **Discussions**: Use GitHub Discussions for questions

- **Email**: Contact the development team



## Acknowledgments



- Flask community for the excellent web framework

- Tailwind CSS for the utility-first CSS framework

- All contributors who have helped improve LilyOpenCms



---



**LilyOpenCms** - Modern content management for the digital age.