storycove/docs/DATA_MODEL.md

# StoryCove Data Model Documentation

## Overview

StoryCove uses PostgreSQL as its primary database with UUID-based primary keys throughout. The data model is designed to support a personal library of short stories with rich metadata, author information, and flexible organization through tags and series.

## Entity Relationship Diagram

```
┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Authors   │────│   Stories    │────│   Series    │
│             │    │              │    │             │
│ - id (PK)   │    │ - id (PK)    │    │ - id (PK)   │
│ - name      │    │ - title      │    │ - name      │
│ - notes     │    │ - content*   │    │ - desc      │
│ - rating    │    │ - rating     │    │             │
│ - avatar    │    │ - volume     │    │             │
└─────────────┘    │ - cover      │    └─────────────┘
       │           │ - word_count │
       │           │ - source_url │
       │           │ - timestamps │
       │           └──────────────┘
       │                  │
       │                  │
┌─────────────┐           │           ┌─────────────┐
│ Author_URLs │           │           │    Tags     │
│             │           │           │             │
│ - author_id │           │           │ - id (PK)   │
│ - url       │           │           │ - name      │
└─────────────┘           │           └─────────────┘
                          │                  │
                          │                  │
                    ┌─────────────┐         │
                    │ Story_Tags  │─────────┘
                    │             │
                    │ - story_id  │
                    │ - tag_id    │
                    └─────────────┘
```

## Detailed Entity Specifications

### Stories Table

**Table Name**: `stories`

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | UUID | PRIMARY KEY, NOT NULL | Unique identifier |
| title | VARCHAR(255) | NOT NULL | Story title |
| summary | TEXT | NULL | Optional story summary |
| description | VARCHAR(1000) | NULL | Optional description |
| content_html | TEXT | NULL | HTML content of the story |
| content_plain | TEXT | NULL | Plain text version (auto-generated) |
| source_url | VARCHAR(255) | NULL | Source URL where story was found |
| cover_path | VARCHAR(255) | NULL | Path to cover image file |
| word_count | INTEGER | NOT NULL, DEFAULT 0 | Word count (auto-calculated) |
| rating | INTEGER | NULL, CHECK (rating >= 1 AND rating <= 5) | Story rating |
| volume | INTEGER | NULL | Volume number if part of series |
| author_id | UUID | FOREIGN KEY | Reference to authors table |
| series_id | UUID | FOREIGN KEY, NULL | Reference to series table |
| created_at | TIMESTAMP | NOT NULL, DEFAULT CURRENT_TIMESTAMP | Creation timestamp |
| updated_at | TIMESTAMP | NOT NULL, DEFAULT CURRENT_TIMESTAMP | Last update timestamp |

**Indexes:**
- Primary key on `id`
- Foreign key index on `author_id`
- Foreign key index on `series_id`
- Index on `created_at` for recent stories queries
- Index on `rating` for top-rated queries
- Unique constraint on `source_url` where not null

**Business Rules:**
- Word count is automatically calculated from `content_plain` or `content_html`
- Plain text content is automatically extracted from HTML content using Jsoup
- Volume is only meaningful when series_id is set
- Rating must be between 1-5 if provided

### Authors Table

**Table Name**: `authors`

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | UUID | PRIMARY KEY, NOT NULL | Unique identifier |
| name | VARCHAR(255) | NOT NULL, UNIQUE | Author name |
| notes | TEXT | NULL | Notes about the author |
| author_rating | INTEGER | NULL, CHECK (author_rating >= 1 AND author_rating <= 5) | Author rating |
| avatar_image_path | VARCHAR(255) | NULL | Path to avatar image |
| created_at | TIMESTAMP | NOT NULL, DEFAULT CURRENT_TIMESTAMP | Creation timestamp |
| updated_at | TIMESTAMP | NOT NULL, DEFAULT CURRENT_TIMESTAMP | Last update timestamp |

**Indexes:**
- Primary key on `id`
- Unique index on `name`
- Index on `author_rating` for top-rated queries

**Business Rules:**
- Author names must be unique across the system
- Rating must be between 1-5 if provided
- Author statistics (story count, average rating) are calculated dynamically

### Author URLs Table

**Table Name**: `author_urls`

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| author_id | UUID | FOREIGN KEY, NOT NULL | Reference to authors table |
| url | VARCHAR(255) | NOT NULL | URL associated with author |

**Indexes:**
- Foreign key index on `author_id`
- Composite index on `(author_id, url)` for uniqueness

**Business Rules:**
- One author can have multiple URLs
- URLs are stored as simple strings without validation
- Duplicate URLs for the same author are prevented by application logic

### Series Table

**Table Name**: `series`

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | UUID | PRIMARY KEY, NOT NULL | Unique identifier |
| name | VARCHAR(255) | NOT NULL, UNIQUE | Series name |
| description | VARCHAR(1000) | NULL | Series description |
| created_at | TIMESTAMP | NOT NULL, DEFAULT CURRENT_TIMESTAMP | Creation timestamp |

**Indexes:**
- Primary key on `id`
- Unique index on `name`

**Business Rules:**
- Series names must be unique
- Stories in a series are ordered by volume number
- Series without stories are allowed (placeholder series)

### Tags Table

**Table Name**: `tags`

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | UUID | PRIMARY KEY, NOT NULL | Unique identifier |
| name | VARCHAR(100) | NOT NULL, UNIQUE | Tag name |
| created_at | TIMESTAMP | NOT NULL, DEFAULT CURRENT_TIMESTAMP | Creation timestamp |

**Indexes:**
- Primary key on `id`
- Unique index on `name`
- Index on `name` for autocomplete queries

**Business Rules:**
- Tag names must be unique and are stored in lowercase
- Tags are created automatically when referenced by stories
- Tag usage statistics are calculated dynamically

### Story Tags Junction Table

**Table Name**: `story_tags`

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| story_id | UUID | FOREIGN KEY, NOT NULL | Reference to stories table |
| tag_id | UUID | FOREIGN KEY, NOT NULL | Reference to tags table |

**Constraints:**
- Primary key on `(story_id, tag_id)`
- Foreign key to `stories(id)` with CASCADE DELETE
- Foreign key to `tags(id)` with CASCADE DELETE

**Indexes:**
- Composite primary key index
- Index on `tag_id` for reverse lookups

## Data Types and Conventions

### UUID Strategy
- All primary keys use UUID (Universally Unique Identifier)
- Generated using `GenerationType.UUID` in Hibernate
- Provides natural uniqueness across distributed systems
- 36-character string representation (e.g., `123e4567-e89b-12d3-a456-426614174000`)

### Timestamp Management
- All entities have `created_at` timestamp
- Stories and Authors have `updated_at` timestamp (automatically updated)
- Series and Tags only have `created_at` (they're rarely modified)
- All timestamps use `LocalDateTime` in Java, stored as `TIMESTAMP` in PostgreSQL

### Text Fields
- **VARCHAR(n)**: For constrained text fields (names, paths, URLs)
- **TEXT**: For unlimited text content (story content, notes, descriptions)
- **HTML Content**: Stored as-is but sanitized on input and output
- **Plain Text**: Automatically extracted from HTML using Jsoup

### Validation Rules
- **Required Fields**: Entity names/titles are always required
- **Length Limits**: Names limited to 255 characters, descriptions to 1000
- **Rating Range**: All ratings constrained to 1-5 range
- **URL Format**: No format validation at database level
- **Uniqueness**: Names are unique within their entity type

## Relationships and Cascading

### One-to-Many Relationships
- **Author → Stories**: Lazy loaded, cascade ALL operations
- **Series → Stories**: Lazy loaded, ordered by volume, cascade ALL
- **Author → Author URLs**: Eager loaded via `@ElementCollection`

### Many-to-Many Relationships
- **Stories ↔ Tags**: Via `story_tags` junction table
- Managed bidirectionally with helper methods
- Cascade DELETE on both sides

### Foreign Key Constraints
- All foreign keys have proper referential integrity
- DELETE operations cascade appropriately
- No orphaned records are allowed

## Performance Considerations

### Indexing Strategy
- Primary keys automatically indexed
- Foreign keys have dedicated indexes
- Frequently queried fields (rating, created_at) are indexed
- Unique constraints automatically create indexes

### Query Optimization
- Lazy loading prevents N+1 queries
- Pagination used for large result sets
- Specialized queries for common access patterns
- Typesense search engine for full-text search (separate from PostgreSQL)

### Data Volume Estimates
- **Stories**: Expected 1K-10K records per user
- **Authors**: Expected 100-1K records per user
- **Tags**: Expected 50-500 records per user
- **Series**: Expected 10-100 records per user
- **Join Tables**: Scale with story count and tagging usage

## Backup and Migration Considerations

### Schema Evolution
- Uses Hibernate `ddl-auto: update` for development
- Production should use controlled migration tools (Flyway/Liquibase)
- UUID keys allow safe data migration between environments

### Data Integrity
- Foreign key constraints ensure referential integrity
- Check constraints validate data ranges
- Application-level validation provides user-friendly error messages
- Unique constraints prevent duplicate data

### Backup Strategy
- Full PostgreSQL dumps for complete backup
- Image files stored separately in filesystem
- Consider incremental backups for large installations
- Test restore procedures regularly

This data model provides a solid foundation for personal story library management with room for future enhancements while maintaining data integrity and performance.