# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

StoryCove is a self-hosted web application for storing, organizing, and reading short stories from internet sources. The project is currently in the specification phase with a comprehensive requirements document.

## Architecture

This is a multi-tier application with the following planned stack:
- **Frontend**: Next.js
- **Backend**: Spring Boot (Java)
- **Database**: PostgreSQL  
- **Search**: Typesense
- **Reverse Proxy**: Nginx
- **Deployment**: Docker & Docker Compose

## Development Commands

### Frontend (Next.js)
- `cd frontend && npm run dev` - Start development server
- `cd frontend && npm run build` - Build for production
- `cd frontend && npm run lint` - Run ESLint
- `cd frontend && npm run type-check` - Run TypeScript compiler

### Backend (Spring Boot)
- `cd backend && ./mvnw spring-boot:run` - Start development server
- `cd backend && ./mvnw test` - Run tests
- `cd backend && ./mvnw clean package` - Build JAR

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

## Current Project State

The repository now has a complete project structure with Docker configuration, frontend Next.js setup, and backend Spring Boot foundation ready for development.

## Key Implementation Details from Specification

### Database Schema
- Stories with HTML content, metadata, ratings, and file attachments
- Authors with profiles, ratings, and URL collections
- Tag-based categorization system
- Series support for multi-part stories
- UUID-based primary keys throughout

### API Design
- RESTful endpoints for stories, authors, tags, and series
- JWT-based authentication with single password
- Multipart form data for file uploads (covers, avatars)
- Full-text search integration with Typesense

### Security Requirements
- HTML sanitization using allowlist (Jsoup on backend)
- Content Security Policy headers
- Input validation and parameterized queries
- Image processing with size limits and format restrictions

### Image Handling
- Cover images for stories (800x1200 max)
- Avatar images for authors (400x400)
- File storage in Docker volumes
- Support for JPG, PNG, WebP formats

## Development Tasks

Based on the specification, implementation should follow this sequence:
1. Docker environment and database setup
2. Spring Boot backend with core CRUD operations
3. Typesense search integration
4. Next.js frontend with authentication
5. Reading interface and user experience features

## Authentication Flow
- Single password authentication (no user accounts)
- JWT tokens stored in httpOnly cookies
- Protected routes via middleware

## File Structure Expectations
When implementation begins, the structure should follow:
```
frontend/          # Next.js application
backend/           # Spring Boot application  
nginx.conf         # Reverse proxy configuration
docker-compose.yml # Container orchestration
.env              # Environment variables
```


## Development Best Practices

- Always create unit and integration tests where it makes sense, when creating new classes.
- **Always check if Test Classes have to be updated after code changes**
- When you fix an error, automatically check and see if this error might also occur in other classes.