storycove/README.md

StoryCove

A self-hosted web application for storing, organizing, and reading short stories from various internet sources.

Quick Start

Option 1: Using Environment-Specific Deployment (Recommended)

1. Deploy for your environment:

# For development
./deploy.sh development

# For staging
./deploy.sh staging

# For production (edit .env.production first with your values)
./deploy.sh production

2. Edit the environment file (.env.development, .env.staging, or .env.production) with your specific configuration

Option 2: Manual Configuration

1. Copy environment variables:

cp .env.example .env

2. Edit .env with secure values for all variables

3. Start the application:

docker-compose up -d

4. Access the application at the URL specified in your environment configuration (default: http://localhost:6925)

Architecture

• Frontend: Next.js (Port 3000)
• Backend: Spring Boot (Port 8080)
• Database: PostgreSQL (Port 5432)
• Search: Typesense (Port 8108)
• Proxy: Nginx (Port 80)

Environment Configuration

StoryCove supports different deployment environments with specific configuration files:

Environment Files

• .env.development - Local development with Docker
• .env.staging - Staging/testing environment
• .env.production - Production deployment
• .env.example - Template with all available options

Key Environment Variables

• STORYCOVE_PUBLIC_URL - The public URL where your app is accessible
• STORYCOVE_CORS_ALLOWED_ORIGINS - Comma-separated list of allowed CORS origins
• DB_PASSWORD - PostgreSQL database password
• JWT_SECRET - Secret key for JWT token signing (minimum 32 characters)
• APP_PASSWORD - Application login password
• TYPESENSE_API_KEY - API key for Typesense search service
• NEXT_PUBLIC_API_URL - Frontend API URL (for development only)

Deployment Examples

For a production deployment at https://stories.example.com:

# Edit .env.production
STORYCOVE_PUBLIC_URL=https://stories.example.com
STORYCOVE_CORS_ALLOWED_ORIGINS=https://stories.example.com

# Deploy
./deploy.sh production

For local development:

./deploy.sh development

Development

Frontend Development

cd frontend
npm install
npm run dev

Backend Development

cd backend
./mvnw spring-boot:run

Commands

• docker-compose up -d - Start all services
• docker-compose down - Stop all services
• docker-compose logs -f [service] - View logs
• docker-compose build - Rebuild containers

✨ Features

📚 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

👤 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 with real-time progress tracking
• Reading Position Memory: Character-based position tracking with smooth auto-scroll restoration
• Smart Tag Filtering: Dynamic tag filters with live story counts in library view
• Keyboard Navigation: Full keyboard accessibility
• Rich Text Editor: Visual and source editing modes for story content
• Progress Indicators: Visual reading progress bars and completion tracking

🔒 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: Complete REST API reference with examples
• Data Model: Detailed database schema and relationships
• Technical Specification: 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, reading_position, last_read_at
• 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, reading progress tracking

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
• POST /{id}/reading-progress - Update reading position
• GET /search - Search stories (Typesense with faceting)
• 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
• Search: Typesense with faceting and full-text search capabilities

Local Development Setup

1. Prerequisites:

   # Required
   - Docker & Docker Compose
   - Node.js 18+ (for frontend development)
   - Java 21+ (for backend development)
   

2. Environment Setup:

   # Copy environment template
   cp .env.example .env
   
   # Edit environment variables
   vim .env
   

3. Database Setup:

   # Start database only
   docker-compose up -d postgres
   

4. Backend Development:

   cd backend
   ./mvnw spring-boot:run
   

5. Frontend Development:

   cd frontend
   npm install
   npm run dev
   

6. Full Stack Development:

   # Start all services
   docker-compose up -d
   
   # View logs
   docker-compose logs -f
   

Testing

# 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.