Update of documentation

2025-07-24 08:51:45 +02:00
parent 77ad643eac
commit 8580d660e9
5 changed files with 2303 additions and 9 deletions
--- a/README.md
+++ b/README.md
@@ -103,14 +103,259 @@ cd backend
 - `docker-compose logs -f [service]` - View logs
 - `docker-compose build` - Rebuild containers

-## Features
+## ✨ Features

- Story management with HTML content support
- Author profiles with ratings and metadata
- Tag-based categorization
- Full-text search capabilities
- Responsive reading interface
- JWT-based authentication
- Docker-based deployment
+### 📚 **Story Management**
+- **Rich Text Support**: HTML content with automatic plain text extraction
+- **Content Sanitization**: Secure HTML processing with customizable sanitization rules
+- **Metadata Management**: Title, summary, description, source URL tracking
+- **Rating System**: 5-star rating system for stories
+- **Word Count**: Automatic word count calculation
+- **Cover Images**: Upload and manage story cover images
+- **Series Support**: Organize stories into series with volume numbers

-For detailed specifications, see `storycove-spec.md`.
+### 👤 **Author Management**
+- **Author Profiles**: Comprehensive author information with notes
+- **Avatar Images**: Upload and manage author profile pictures
+- **URL Collections**: Track multiple URLs per author (websites, social media, etc.)
+- **Author Ratings**: Rate authors with 5-star system
+- **Statistics**: View author statistics and story counts
+
+### 🏷️ **Organization & Discovery**
+- **Tag System**: Flexible tagging with autocomplete
+- **Series Organization**: Group related stories with volume ordering
+- **Search & Filter**: Full-text search powered by Typesense
+- **Advanced Filtering**: Filter by author, tags, ratings, and more
+- **Smart Suggestions**: Auto-complete for tags and search queries
+
+### 🎨 **User Experience**
+- **Dark/Light Mode**: Automatic theme switching with system preference detection
+- **Responsive Design**: Optimized for desktop, tablet, and mobile
+- **Reading Mode**: Distraction-free reading interface
+- **Keyboard Navigation**: Full keyboard accessibility
+- **Rich Text Editor**: Visual and source editing modes for story content
+
+### 🔒 **Security & Administration**
+- **JWT Authentication**: Secure token-based authentication
+- **Single Password**: Simplified access control
+- **HTML Sanitization**: Prevent XSS attacks with configurable sanitization
+- **CORS Configuration**: Environment-specific CORS settings
+- **File Upload Security**: Secure image upload with validation
+
+### 🚀 **Technical Features**
+- **Full-Text Search**: Powered by Typesense search engine
+- **RESTful API**: Comprehensive REST API for all operations
+- **Database Optimization**: PostgreSQL with proper indexing
+- **Image Processing**: Automatic image optimization and storage
+- **Environment Configuration**: Multi-environment deployment support
+- **Docker Deployment**: Complete containerized deployment
+
+### 📊 **Analytics & Statistics**
+- **Usage Statistics**: Track story counts, tag usage, and more
+- **Rating Analytics**: View average ratings and distributions
+- **Search Analytics**: Monitor search performance and suggestions
+- **Storage Metrics**: Track image storage and database usage
+
+## 📖 Documentation
+
+- **[API Documentation](docs/API.md)**: Complete REST API reference with examples
+- **[Data Model](docs/DATA_MODEL.md)**: Detailed database schema and relationships
+- **[Technical Specification](storycove-spec.md)**: Comprehensive technical specification
+- **Environment Configuration**: Multi-environment deployment setup (see above)
+- **Development Setup**: Local development environment setup (see below)
+
+## 🗄️ Data Model
+
+StoryCove uses a PostgreSQL database with the following core entities:
+
+### **Stories**
+- **Primary Key**: UUID
+- **Fields**: title, summary, description, content_html, content_plain, source_url, word_count, rating, volume, cover_path
+- **Relationships**: Many-to-One with Author, Many-to-One with Series, Many-to-Many with Tags
+- **Features**: Automatic word count calculation, HTML sanitization, plain text extraction
+
+### **Authors**
+- **Primary Key**: UUID  
+- **Fields**: name, notes, author_rating, avatar_image_path
+- **Relationships**: One-to-Many with Stories, One-to-Many with Author URLs
+- **Features**: URL collection storage, rating system, statistics calculation
+
+### **Series**
+- **Primary Key**: UUID
+- **Fields**: name, description
+- **Relationships**: One-to-Many with Stories (ordered by volume)
+- **Features**: Volume-based story ordering, navigation methods
+
+### **Tags**
+- **Primary Key**: UUID
+- **Fields**: name (unique)
+- **Relationships**: Many-to-Many with Stories
+- **Features**: Autocomplete support, usage statistics
+
+### **Join Tables**
+- **story_tags**: Links stories to tags
+- **author_urls**: Stores multiple URLs per author
+
+## 🔌 REST API Reference
+
+### **Authentication** (`/api/auth`)
+- `POST /login` - Authenticate with password
+- `POST /logout` - Clear authentication token
+- `GET /verify` - Verify token validity
+
+### **Stories** (`/api/stories`)
+- `GET /` - List stories (paginated)
+- `GET /{id}` - Get specific story  
+- `POST /` - Create new story
+- `PUT /{id}` - Update story
+- `DELETE /{id}` - Delete story
+- `POST /{id}/cover` - Upload cover image
+- `DELETE /{id}/cover` - Remove cover image
+- `POST /{id}/rating` - Set story rating
+- `POST /{id}/tags/{tagId}` - Add tag to story
+- `DELETE /{id}/tags/{tagId}` - Remove tag from story
+- `GET /search` - Search stories (Typesense)
+- `GET /search/suggestions` - Get search suggestions
+- `GET /author/{authorId}` - Stories by author
+- `GET /series/{seriesId}` - Stories in series
+- `GET /tags/{tagName}` - Stories with tag
+- `GET /recent` - Recent stories
+- `GET /top-rated` - Top-rated stories
+
+### **Authors** (`/api/authors`)
+- `GET /` - List authors (paginated)
+- `GET /{id}` - Get specific author
+- `POST /` - Create new author
+- `PUT /{id}` - Update author (JSON or multipart)
+- `DELETE /{id}` - Delete author
+- `POST /{id}/avatar` - Upload avatar image
+- `DELETE /{id}/avatar` - Remove avatar image
+- `POST /{id}/rating` - Set author rating
+- `POST /{id}/urls` - Add URL to author
+- `DELETE /{id}/urls` - Remove URL from author
+- `GET /search` - Search authors
+- `GET /search-typesense` - Advanced author search
+- `GET /top-rated` - Top-rated authors
+
+### **Tags** (`/api/tags`)
+- `GET /` - List tags (paginated)
+- `GET /{id}` - Get specific tag
+- `POST /` - Create new tag
+- `PUT /{id}` - Update tag
+- `DELETE /{id}` - Delete tag
+- `GET /search` - Search tags
+- `GET /autocomplete` - Tag autocomplete
+- `GET /popular` - Most used tags
+- `GET /unused` - Unused tags
+- `GET /stats` - Tag statistics
+
+### **Series** (`/api/series`)
+- `GET /` - List series (paginated)
+- `GET /{id}` - Get specific series
+- `POST /` - Create new series
+- `PUT /{id}` - Update series
+- `DELETE /{id}` - Delete series
+- `GET /search` - Search series
+- `GET /with-stories` - Series with stories
+- `GET /popular` - Popular series
+- `GET /empty` - Empty series
+- `GET /stats` - Series statistics
+
+### **Files** (`/api/files`)
+- `POST /upload/cover` - Upload cover image
+- `POST /upload/avatar` - Upload avatar image
+- `GET /images/**` - Serve image files
+- `DELETE /images` - Delete image file
+
+### **Search** (`/api/search`)
+- `POST /reindex` - Reindex all content
+- `GET /health` - Search service health
+
+### **Configuration** (`/api/config`)
+- `GET /html-sanitization` - Get HTML sanitization rules
+
+### **Request/Response Format**
+All API endpoints use JSON format with proper HTTP status codes:
+- **200**: Success
+- **201**: Created
+- **400**: Bad Request (validation errors)
+- **401**: Unauthorized
+- **404**: Not Found
+- **500**: Internal Server Error
+
+### **Authentication**
+- JWT tokens provided via httpOnly cookies
+- All endpoints (except `/api/auth/login`) require authentication
+- Tokens expire after 24 hours
+
+## 🔧 Development
+
+### **Technology Stack**
+- **Frontend**: Next.js 14, TypeScript, Tailwind CSS, React
+- **Backend**: Spring Boot 3, Java 21, PostgreSQL, Typesense
+- **Infrastructure**: Docker, Docker Compose, Nginx
+- **Security**: JWT authentication, HTML sanitization, CORS
+
+### **Local Development Setup**
+
+1. **Prerequisites**:
+   ```bash
+   # Required
+   - Docker & Docker Compose
+   - Node.js 18+ (for frontend development)
+   - Java 21+ (for backend development)
+   ```
+
+2. **Environment Setup**:
+   ```bash
+   # Copy environment template
+   cp .env.example .env
+   
+   # Edit environment variables
+   vim .env
+   ```
+
+3. **Database Setup**:
+   ```bash
+   # Start database only
+   docker-compose up -d postgres
+   ```
+
+4. **Backend Development**:
+   ```bash
+   cd backend
+   ./mvnw spring-boot:run
+   ```
+
+5. **Frontend Development**:
+   ```bash
+   cd frontend
+   npm install
+   npm run dev
+   ```
+
+6. **Full Stack Development**:
+   ```bash
+   # Start all services
+   docker-compose up -d
+   
+   # View logs
+   docker-compose logs -f
+   ```
+
+### **Testing**
+```bash
+# Backend tests
+cd backend && ./mvnw test
+
+# Frontend build
+cd frontend && npm run build
+
+# Frontend linting
+cd frontend && npm run lint
+```
+
+### **Database Migrations**
+The application uses Hibernate with `ddl-auto: update` for schema management. For production deployments, consider using Flyway or Liquibase for controlled migrations.
+
+For detailed technical specifications, see `storycove-spec.md`.