timeline-frontend/BACKEND_API_SPECIFICATION.md

# Backend API Specification for Personal User Enhancements

## Overview

This document specifies the backend API requirements for the Personal User Enhancements feature set. The backend team should implement these endpoints in the `timeline-server` Java application.

**Base URL**: `/api/v1`

**Technology Stack**:
- Java-based REST API
- PostgreSQL/MySQL database
- Redis for caching
- WebSocket (STOMP) for real-time notifications
- jqwik library for property-based testing

## Database Schema Requirements

### Albums Table
```sql
CREATE TABLE albums (
  id VARCHAR(36) PRIMARY KEY,
  user_id VARCHAR(36) NOT NULL,
  name VARCHAR(255) NOT NULL,
  description TEXT,
  cover_photo_id VARCHAR(36),
  photo_count INT DEFAULT 0,
  created_at TIMESTAMP NOT NULL,
  updated_at TIMESTAMP NOT NULL,
  version INT DEFAULT 0,
  INDEX idx_user_id (user_id),
  INDEX idx_created_at (created_at)
);
```

### Album Photos Table
```sql
CREATE TABLE album_photos (
  id VARCHAR(36) PRIMARY KEY,
  album_id VARCHAR(36) NOT NULL,
  photo_id VARCHAR(36) NOT NULL,
  display_order INT NOT NULL,
  added_at TIMESTAMP NOT NULL,
  FOREIGN KEY (album_id) REFERENCES albums(id) ON DELETE CASCADE,
  INDEX idx_album_id (album_id),
  INDEX idx_photo_id (photo_id),
  UNIQUE KEY unique_album_photo (album_id, photo_id)
);
```

### Smart Collections Table
```sql
CREATE TABLE smart_collections (
  id VARCHAR(36) PRIMARY KEY,
  user_id VARCHAR(36) NOT NULL,
  type ENUM('date', 'location', 'person') NOT NULL,
  name VARCHAR(255) NOT NULL,
  criteria JSON NOT NULL,
  content_count INT DEFAULT 0,
  thumbnail_url VARCHAR(512),
  created_at TIMESTAMP NOT NULL,
  updated_at TIMESTAMP NOT NULL,
  INDEX idx_user_id (user_id),
  INDEX idx_type (type)
);
```

### Comments Table
```sql
CREATE TABLE comments (
  id VARCHAR(36) PRIMARY KEY,
  entity_type ENUM('story', 'photo') NOT NULL,
  entity_id VARCHAR(36) NOT NULL,
  user_id VARCHAR(36) NOT NULL,
  text TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL,
  updated_at TIMESTAMP,
  is_edited BOOLEAN DEFAULT FALSE,
  INDEX idx_entity (entity_type, entity_id),
  INDEX idx_user_id (user_id),
  INDEX idx_created_at (created_at)
);
```

### Reactions Table
```sql
CREATE TABLE reactions (
  id VARCHAR(36) PRIMARY KEY,
  entity_type ENUM('story', 'photo') NOT NULL,
  entity_id VARCHAR(36) NOT NULL,
  user_id VARCHAR(36) NOT NULL,
  type ENUM('like', 'love', 'laugh', 'wow', 'sad') NOT NULL,
  created_at TIMESTAMP NOT NULL,
  INDEX idx_entity (entity_type, entity_id),
  INDEX idx_user_id (user_id),
  UNIQUE KEY unique_user_entity_reaction (entity_type, entity_id, user_id)
);
```

### User Preferences Table
```sql
CREATE TABLE user_preferences (
  user_id VARCHAR(36) PRIMARY KEY,
  theme_mode ENUM('light', 'dark', 'auto') DEFAULT 'auto',
  color_scheme VARCHAR(50) DEFAULT 'default',
  gallery_layout ENUM('grid', 'list') DEFAULT 'grid',
  timeline_layout ENUM('grid', 'list') DEFAULT 'grid',
  album_layout ENUM('grid', 'list') DEFAULT 'grid',
  card_size ENUM('small', 'medium', 'large') DEFAULT 'medium',
  timeline_display_mode ENUM('chronological', 'grouped', 'masonry') DEFAULT 'chronological',
  updated_at TIMESTAMP NOT NULL
);
```

### User Profile Table
```sql
CREATE TABLE user_profiles (
  user_id VARCHAR(36) PRIMARY KEY,
  cover_photo_url VARCHAR(512),
  bio TEXT,
  updated_at TIMESTAMP NOT NULL
);

CREATE TABLE profile_custom_fields (
  id VARCHAR(36) PRIMARY KEY,
  user_id VARCHAR(36) NOT NULL,
  name VARCHAR(100) NOT NULL,
  value TEXT NOT NULL,
  visibility ENUM('public', 'private') DEFAULT 'public',
  display_order INT NOT NULL,
  FOREIGN KEY (user_id) REFERENCES user_profiles(user_id) ON DELETE CASCADE,
  INDEX idx_user_id (user_id)
);
```

### User Statistics Table (Cache)
```sql
CREATE TABLE user_statistics (
  user_id VARCHAR(36) PRIMARY KEY,
  total_photos INT DEFAULT 0,
  total_stories INT DEFAULT 0,
  total_storage_bytes BIGINT DEFAULT 0,
  calculated_at TIMESTAMP NOT NULL,
  INDEX idx_calculated_at (calculated_at)
);

CREATE TABLE upload_trends (
  id VARCHAR(36) PRIMARY KEY,
  user_id VARCHAR(36) NOT NULL,
  period VARCHAR(10) NOT NULL,
  photo_count INT DEFAULT 0,
  story_count INT DEFAULT 0,
  storage_bytes BIGINT DEFAULT 0,
  FOREIGN KEY (user_id) REFERENCES user_statistics(user_id) ON DELETE CASCADE,
  INDEX idx_user_period (user_id, period)
);
```

### Sync Changes Table
```sql
CREATE TABLE sync_changes (
  id VARCHAR(36) PRIMARY KEY,
  user_id VARCHAR(36) NOT NULL,
  entity_type ENUM('story', 'album', 'photo') NOT NULL,
  entity_id VARCHAR(36) NOT NULL,
  operation ENUM('create', 'update', 'delete') NOT NULL,
  data JSON NOT NULL,
  timestamp TIMESTAMP NOT NULL,
  synced BOOLEAN DEFAULT FALSE,
  synced_at TIMESTAMP,
  error TEXT,
  INDEX idx_user_synced (user_id, synced),
  INDEX idx_timestamp (timestamp)
);
```

## API Endpoints

### Smart Collections API

#### GET /api/v1/collections/smart
List all smart collections for the authenticated user.

**Response**:
```json
[
  {
    "id": "uuid",
    "userId": "uuid",
    "type": "date",
    "name": "2024",
    "criteria": { "year": 2024 },
    "contentCount": 150,
    "thumbnailUrl": "https://...",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]
```

#### GET /api/v1/collections/smart/:id/content
Get content within a specific smart collection.

**Query Parameters**:
- `page` (int, default: 1)
- `pageSize` (int, default: 20)

**Response**:
```json
{
  "collectionId": "uuid",
  "items": [
    {
      "id": "uuid",
      "type": "photo",