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:

Docker environment and database setup
Spring Boot backend with core CRUD operations
Typesense search integration
Next.js frontend with authentication
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

3.1 KiB Raw Blame History