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:
```bash
# 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:
```bash
cp .env.example .env
```

2. Edit `.env` with secure values for all variables

3. Start the application:
```bash
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`:
```bash
# 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:
```bash
./deploy.sh development
```

## Development

### Frontend Development
```bash
cd frontend
npm install
npm run dev
```

### Backend Development
```bash
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
- **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`.