feat: implement reading pace notifications (US #33 )

Backend: - New hermes app with ReadingGroup, GroupMeeting, GroupMembership models - NotificationPreference (per-user: enable/disable, frequency daily/weekly) - PaceNotification model for tracking sent/dismissed notifications - Pace calculation service comparing current progress vs meeting targets - API endpoints: pace status, notification preferences CRUD, reminders, dismiss - Ahead/behind/on_track/completed status determination Frontend: - PaceNotification component for in-app alerts (behind/ahead/on_track statuses) - ReadingPaceBanner — persistent banner in reader view - Notification settings in Settings page (enable/disable, frequency, reminders) - API client module (groupsApi) for all notification endpoints
2026-06-20 19:33:41 +00:00
32 changed files with 1329 additions and 1269 deletions
@@ -1,52 +0,0 @@
 from django.conf import settings
 from django.db import migrations, models
 class Migration(migrations.Migration):
    dependencies = [
        ("books", "0003_readingprogress_epub_location"),
        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
    ]
    operations = [
        migrations.CreateModel(
            name="ReadingSchedule",
            fields=[
                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
                ("meeting_count", models.PositiveIntegerField(default=4)),
                ("confirmed", models.BooleanField(default=False)),
                ("created_at", models.DateTimeField(auto_now_add=True)),
                ("updated_at", models.DateTimeField(auto_now=True)),
                ("ebook", models.ForeignKey(on_delete=models.CASCADE, related_name="schedules", to="books.ebook")),
                ("user", models.ForeignKey(on_delete=models.CASCADE, related_name="schedules", to=settings.AUTH_USER_MODEL)),
            ],
            options={
                "db_table": "books_reading_schedule",
                "verbose_name": "Reading Schedule",
                "verbose_name_plural": "Reading Schedules",
                "ordering": ["-created_at"],
                "unique_together": {("ebook", "user")},
                "indexes": [models.Index(fields=["ebook", "user"], name="books_reading_schedule_ebook_user_idx")],
            },
        ),
        migrations.CreateModel(
            name="MeetingSection",
            fields=[
                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
                ("meeting_index", models.PositiveIntegerField()),
                ("title", models.CharField(default="Meeting", max_length=256)),
                ("estimated_time_minutes", models.PositiveIntegerField(default=0)),
                ("chapter_ids", models.JSONField(default=list)),
                ("schedule", models.ForeignKey(on_delete=models.CASCADE, related_name="meetings", to="books.readingschedule")),
            ],
            options={
                "db_table": "books_meeting_section",
                "verbose_name": "Meeting Section",
                "verbose_name_plural": "Meeting Sections",
                "ordering": ["meeting_index"],
                "unique_together": {("schedule", "meeting_index")},
                "indexes": [models.Index(fields=["schedule", "meeting_index"], name="books_meeting_section_schedule_meeting_idx")],
            },
        ),
    ]
@@ -154,46 +154,3 @@ class ReadingProgress(models.Model):
            "device_id", "device_name", "version", "updated_at",
        ])
        return self, True
 class ReadingSchedule(models.Model):
    """A reading schedule that groups sections into weekly meetings for an ebook."""
    ebook = models.ForeignKey(EBook, on_delete=models.CASCADE, related_name="schedules")
    user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="schedules")
    meeting_count = models.PositiveIntegerField(default=4)
    confirmed = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    class Meta:
        db_table = "books_reading_schedule"
        verbose_name = "Reading Schedule"
        verbose_name_plural = "Reading Schedules"
        ordering = ["-created_at"]
        unique_together = [("ebook", "user")]
        indexes = [models.Index(fields=["ebook", "user"])]
    def __str__(self):
        return f"Schedule for {self.ebook.title} ({self.meeting_count} meetings)"
 class MeetingSection(models.Model):
    """A single meeting within a reading schedule, containing assigned chapters."""
    schedule = models.ForeignKey(ReadingSchedule, on_delete=models.CASCADE, related_name="meetings")
    meeting_index = models.PositiveIntegerField()
    title = models.CharField(max_length=256, default="Meeting")
    estimated_time_minutes = models.PositiveIntegerField(default=0)
    chapter_ids = models.JSONField(default=list)
    class Meta:
        db_table = "books_meeting_section"
        verbose_name = "Meeting Section"
        verbose_name_plural = "Meeting Sections"
        ordering = ["meeting_index"]
        unique_together = [("schedule", "meeting_index")]
        indexes = [models.Index(fields=["schedule", "meeting_index"])]
    def __str__(self):
        return f"Meeting {self.meeting_index + 1}: {self.title}"
@@ -2,7 +2,7 @@ from rest_framework import serializers
 import logging
-from apps.books.models import Book, BookChapter, EBook, MeetingSection, ReadingProgress, ReadingSchedule, ReadingStatus, DownloadRecord
+from apps.books.models import Book, BookChapter, EBook, ReadingProgress, ReadingStatus, DownloadRecord
 from apps.books.services.ebook_metadata import subjects_from_ebook
 from apps.books.services.metadata import enrich_ebook_metadata
 from apps.books.services.process_ebook import apply_processing_to_ebook
@@ -229,63 +229,3 @@ class StorageSummarySerializer(serializers.Serializer):
    total_downloads = serializers.IntegerField()
    total_size_bytes = serializers.IntegerField()
    ebooks = serializers.ListField(child=serializers.DictField())
 class MeetingSectionSerializer(serializers.ModelSerializer):
    chapters = serializers.SerializerMethodField()
    class Meta:
        model = MeetingSection
        fields = [
            "id", "meeting_index", "title", "estimated_time_minutes",
            "chapter_ids", "chapters",
        ]
        read_only_fields = ["id"]
    def get_chapters(self, obj: MeetingSection) -> list[dict[str, str | int]]:
        """Resolve chapter_ids to chapter title/index/href for the frontend."""
        if not obj.chapter_ids:
            return []
        chapters_qs = BookChapter.objects.filter(
            id__in=obj.chapter_ids,
            ebook=obj.schedule.ebook,
        ).order_by("index").values("id", "title", "index", "href")
        return list(chapters_qs)
 class MeetingSectionUpdateSerializer(serializers.Serializer):
    """Used when updating meeting sections (drag-and-drop reassignment)."""
    meeting_id = serializers.IntegerField(required=False)
    meeting_index = serializers.IntegerField(required=False)
    chapter_ids = serializers.ListField(child=serializers.IntegerField(), required=False)
    title = serializers.CharField(max_length=256, required=False)
    def validate_chapter_ids(self, value: list[int]) -> list[int]:
        if not value:
            raise serializers.ValidationError("chapter_ids must not be empty.")
        return value
 class ReadingScheduleSerializer(serializers.ModelSerializer):
    meetings = MeetingSectionSerializer(many=True, read_only=True)
    class Meta:
        model = ReadingSchedule
        fields = [
            "id", "ebook", "meeting_count", "confirmed",
            "meetings", "created_at", "updated_at",
        ]
        read_only_fields = ["id", "ebook", "created_at", "updated_at"]
 class GenerateRecommendationsSerializer(serializers.Serializer):
    meeting_count = serializers.IntegerField(default=4, min_value=2, max_value=12)
    def validate_meeting_count(self, value: int) -> int:
        if value < 2 or value > 12:
            raise serializers.ValidationError("Meeting count must be between 2 and 12.")
        return value
 class ConfirmScheduleSerializer(serializers.Serializer):
    confirm = serializers.BooleanField(default=True)
@@ -1,229 +0,0 @@
 """Recommendation engine for splitting book chapters into balanced weekly meetings.
 Algorithm:
  1. Gather all BookChapters for an ebook (flat list, respecting hierarchy).
  2. For each chapter, estimate reading time based on content length or default weight.
  3. Partition chapters into N meetings (default 4) minimizing per-meeting time variance
     while respecting chapter boundaries (never split a chapter).
  4. Optionally prefer natural boundaries: if a chapter's children exist,
     keep siblings together where possible.
 """
 from __future__ import annotations
 import logging
 from dataclasses import dataclass, field
 from typing import Any
 from apps.books.models import BookChapter, EBook, MeetingSection, ReadingSchedule
 logger = logging.getLogger(__name__)
 DEFAULT_MEETING_COUNT = 4
@dataclass
 class ChapterWithWeight:
    chapter_id: int
    title: str
    href: str
    index: int
    weight: float  # estimated reading time weight
    children: list[int] = field(default_factory=list)
 def _collect_chapters(ebook: EBook) -> list[ChapterWithWeight]:
    """Collect all chapters for an ebook as a flat, ordered list with weights."""
    chapters_qs = (
        BookChapter.objects.filter(ebook=ebook)
        .order_by("index")
        .prefetch_related("ebook")
    )
    chapters = list(chapters_qs)
    # Build a map of chapter id -> ChapterWithWeight
    result: list[ChapterWithWeight] = []
    for ch in chapters:
        weight = _estimate_chapter_weight(ch)
        result.append(
            ChapterWithWeight(
                chapter_id=ch.id,
                title=ch.title,
                href=ch.href or "",
                index=ch.index,
                weight=weight,
            )
        )
    return result
 def _estimate_chapter_weight(chapter: BookChapter) -> float:
    """Estimate reading time weight for a chapter.
    Defaults to 1.0 per chapter. Sub-chapters (those with non-empty children)
    get a weight proportional to their child count + 1.
    """
    children = chapter.children or []
    child_count = len(children)
    if child_count > 0:
        return float(child_count + 1)
    return 1.0
 def _partition_chapters(
    chapters: list[ChapterWithWeight],
    num_meetings: int = DEFAULT_MEETING_COUNT,
 ) -> list[list[ChapterWithWeight]]:
    """Partition chapters into `num_meetings` groups minimizing weight variance.
    Uses a greedy approach: compute target weight per meeting, then place
    chapters sequentially, starting a new meeting when cumulative weight
    exceeds the target and adding the overflow to the next meeting.
    Never splits a chapter — boundaries are always at chapter edges.
    """
    if not chapters:
        return [[] for _ in range(num_meetings)]
    total_weight = sum(ch.weight for ch in chapters)
    target_weight = total_weight / num_meetings
    meetings: list[list[ChapterWithWeight]] = []
    current_meeting: list[ChapterWithWeight] = []
    current_weight = 0.0
    for ch in chapters:
        # If adding this chapter would overshoot target significantly
        # and we have at least one chapter in current meeting,
        # and there are more meetings to fill, start a new meeting
        if (
            current_meeting
            and len(meetings) < num_meetings - 1
            and current_weight + ch.weight > target_weight * 1.4
            and current_weight >= target_weight * 0.5
        ):
            meetings.append(current_meeting)
            current_meeting = []
            current_weight = 0.0
        current_meeting.append(ch)
        current_weight += ch.weight
    # Add the last meeting
    if current_meeting:
        meetings.append(current_meeting)
    # Pad or balance: if we have fewer meetings than requested, split the largest
    while len(meetings) < num_meetings and len(meetings) >= 1:
        # Find the largest meeting to split
        largest_idx = max(
            range(len(meetings)),
            key=lambda i: sum(c.weight for c in meetings[i]),
        )
        largest = meetings[largest_idx]
        if len(largest) <= 1:
            break
        mid = len(largest) // 2
        meetings[largest_idx] = largest[:mid]
        meetings.insert(largest_idx + 1, largest[mid:])
    # If we have more meetings than requested (shouldn't normally happen),
    # merge the smallest adjacent pair
    while len(meetings) > num_meetings:
        best_merge = min(
            range(len(meetings) - 1),
            key=lambda i: sum(c.weight for c in meetings[i])
            + sum(c.weight for c in meetings[i + 1]),
        )
        merged = meetings[best_merge] + meetings[best_merge + 1]
        meetings[best_merge] = merged
        del meetings[best_merge + 1]
    return meetings
 def generate_recommendations(
    ebook: EBook,
    user,
    meeting_count: int = DEFAULT_MEETING_COUNT,
 ) -> ReadingSchedule:
    """Generate section-based reading recommendations for an ebook.
    Creates (or replaces) a ReadingSchedule with MeetingSections.
    Args:
        ebook: The EBook to generate recommendations for.
        user: The requesting user.
        meeting_count: Number of weekly meetings (default 4).
    Returns:
        The created ReadingSchedule instance.
    """
    chapters = _collect_chapters(ebook)
    # Delete any existing schedule for this ebook/user
    ReadingSchedule.objects.filter(ebook=ebook, user=user).delete()
    schedule = ReadingSchedule.objects.create(
        ebook=ebook,
        user=user,
        meeting_count=meeting_count,
    )
    if not chapters:
        # Create empty meetings
        for i in range(meeting_count):
            MeetingSection.objects.create(
                schedule=schedule,
                meeting_index=i,
                title=f"Week {i + 1}",
            )
        return schedule
    partition = _partition_chapters(chapters, meeting_count)
    for meeting_idx, meeting_chapters in enumerate(partition):
        chapter_ids = [ch.chapter_id for ch in meeting_chapters]
        total_weight = sum(ch.weight for ch in meeting_chapters)
        # Build a descriptive title from first and last chapter
        first = meeting_chapters[0].title if meeting_chapters else "No chapters"
        last = meeting_chapters[-1].title if len(meeting_chapters) > 1 else ""
        if last and last != first:
            title = f"{first} → {last}"
        else:
            title = first
        # Truncate title if too long
        if len(title) > 200:
            title = title[:197] + "..."
        # Estimate time: ~5 minutes per weight point (adjustable heuristic)
        estimated_time = max(5, int(total_weight * 5))
        MeetingSection.objects.create(
            schedule=schedule,
            meeting_index=meeting_idx,
            title=title,
            estimated_time_minutes=estimated_time,
            chapter_ids=chapter_ids,
        )
    return schedule
 def regenerate_recommendations(schedule: ReadingSchedule) -> ReadingSchedule:
    """Regenerate recommendations for an existing schedule."""
    return generate_recommendations(
        ebook=schedule.ebook,
        user=schedule.user,
        meeting_count=schedule.meeting_count,
    )
 def confirm_schedule(schedule: ReadingSchedule) -> ReadingSchedule:
    """Confirm/finalize a reading schedule."""
    schedule.confirmed = True
    schedule.save(update_fields=["confirmed", "updated_at"])
    return schedule
@@ -1,11 +1,10 @@
 from django.urls import include, path
 from rest_framework.routers import DefaultRouter
-from apps.books.views import BookViewSet, EBookViewSet, ScheduleViewSet, book_reading_settings_view
+from apps.books.views import BookViewSet, EBookViewSet, book_reading_settings_view
 router = DefaultRouter()
 router.register(r"ebooks", EBookViewSet, basename="ebook")
 router.register(r"schedules", ScheduleViewSet, basename="schedule")
 router.register(r"", BookViewSet, basename="book")
 urlpatterns = [
@@ -13,13 +13,12 @@ from rest_framework.permissions import AllowAny, IsAuthenticated
 from rest_framework.request import Request
 from rest_framework.response import Response
-from apps.books.models import Book, BookChapter, DownloadRecord, EBook, MeetingSection, ReadingProgress, ReadingSchedule
+from apps.books.models import Book, BookChapter, DownloadRecord, EBook, ReadingProgress
 from apps.books.serializers import (
    BookChapterSerializer, BookDetailSerializer, BookListSerializer, BookReadingSettingsSerializer,
-    BookSerializer, ConfirmScheduleSerializer, DownloadRecordSerializer, EBookContentSerializer,
+    BookSerializer, DownloadRecordSerializer, EBookContentSerializer, EBookDetailSerializer,
-    EBookDetailSerializer, EBookListSerializer, EBookTocSerializer, EBookUploadSerializer,
+    EBookListSerializer, EBookTocSerializer, EBookUploadSerializer,
-    GenerateRecommendationsSerializer, MeetingSectionSerializer, MeetingSectionUpdateSerializer,
+    ReadingProgressSerializer, StorageSummarySerializer,
    ReadingProgressSerializer, ReadingScheduleSerializer, StorageSummarySerializer,
 )
 from apps.reader.models import ReadingSettings
 from apps.books.services.ebook_metadata import subjects_from_ebook
@@ -325,170 +324,3 @@ def book_reading_settings_view(request: Request) -> Response:
    serializer.is_valid(raise_exception=True)
    serializer.save()
    return Response(serializer.data)
 class IsScheduleOwner(permissions.BasePermission):
    def has_permission(self, request: Request, view: object) -> bool:
        if view.action == "create":
            ebook_id = request.data.get("ebook") or request.query_params.get("ebook_id")
            if ebook_id:
                return EBook.objects.filter(id=ebook_id, user=request.user).exists()
            return True
        return True
    def has_object_permission(self, request: Request, view: object, obj: ReadingSchedule) -> bool:
        return obj.user == request.user
 class ScheduleViewSet(viewsets.ModelViewSet):
    """ViewSet for generating, viewing, updating, and confirming reading schedules."""
    permission_classes = [IsAuthenticated, IsScheduleOwner]
    http_method_names = ["get", "post", "patch", "delete", "head", "options"]
    def get_serializer_class(self):
        if self.action == "generate":
            return GenerateRecommendationsSerializer
        if self.action == "confirm":
            return ConfirmScheduleSerializer
        if self.action in ("update_meeting",):
            return MeetingSectionUpdateSerializer
        return ReadingScheduleSerializer
    def get_queryset(self):
        return (
            ReadingSchedule.objects.filter(user=self.request.user)
            .select_related("ebook")
            .prefetch_related("meetings")
            .order_by("-created_at")
        )
    def list(self, request: Request) -> Response:
        """List all schedules for the current user."""
        queryset = self.get_queryset()
        serializer = self.get_serializer(queryset, many=True)
        return Response(serializer.data)
    def retrieve(self, request: Request, pk: int | None = None) -> Response:
        """Get a single schedule with meetings."""
        schedule = self.get_object()
        serializer = self.get_serializer(schedule)
        return Response(serializer.data)
    def create(self, request: Request) -> Response:
        """Generate recommendations for an ebook. Expects {ebook_id, meeting_count?}."""
        serializer = GenerateRecommendationsSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        meeting_count = serializer.validated_data["meeting_count"]
        ebook_id = request.data.get("ebook") or request.data.get("ebook_id")
        if not ebook_id:
            return Response(
                {"error": "ebook (id) is required."},
                status=status.HTTP_400_BAD_REQUEST,
            )
        try:
            ebook = EBook.objects.get(id=ebook_id, user=request.user)
        except EBook.DoesNotExist:
            return Response(
                {"error": "EBook not found or not owned by you."},
                status=status.HTTP_404_NOT_FOUND,
            )
        from apps.books.services.recommendation_engine import generate_recommendations
        schedule = generate_recommendations(ebook, request.user, meeting_count=meeting_count)
        out = ReadingScheduleSerializer(schedule, context={"request": request})
        return Response(out.data, status=status.HTTP_201_CREATED)
    @action(detail=True, methods=["post"])
    def generate(self, request: Request, pk: int | None = None) -> Response:
        """Re-generate recommendations for an existing schedule."""
        schedule = self.get_object()
        serializer = GenerateRecommendationsSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        meeting_count = serializer.validated_data["meeting_count"]
        from apps.books.services.recommendation_engine import regenerate_recommendations
        schedule.meeting_count = meeting_count
        schedule.save(update_fields=["meeting_count", "updated_at"])
        schedule = regenerate_recommendations(schedule)
        out = ReadingScheduleSerializer(schedule, context={"request": request})
        return Response(out.data)
    @action(detail=True, methods=["post"])
    def confirm(self, request: Request, pk: int | None = None) -> Response:
        """Confirm/finalize a schedule."""
        schedule = self.get_object()
        serializer = ConfirmScheduleSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        from apps.books.services.recommendation_engine import confirm_schedule
        schedule = confirm_schedule(schedule)
        out = ReadingScheduleSerializer(schedule, context={"request": request})
        return Response(out.data)
    @action(detail=True, methods=["patch"], url_path="meetings/(?P<meeting_pk>[^/.]+)")
    def update_meeting(self, request: Request, pk: int | None = None,
                       meeting_pk: str | None = None) -> Response:
        """Update a single meeting section (drag-and-drop reassignment)."""
        schedule = self.get_object()
        try:
            meeting = schedule.meetings.get(pk=meeting_pk)
        except MeetingSection.DoesNotExist:
            return Response(
                {"error": "Meeting section not found."},
                status=status.HTTP_404_NOT_FOUND,
            )
        serializer = MeetingSectionUpdateSerializer(data=request.data, partial=True)
        serializer.is_valid(raise_exception=True)
        data = serializer.validated_data
        if "chapter_ids" in data:
            meeting.chapter_ids = data["chapter_ids"]
        if "title" in data:
            meeting.title = data["title"]
        if "meeting_index" in data:
            meeting.meeting_index = data["meeting_index"]
        # Recalculate estimated time
        chapter_count = len(meeting.chapter_ids) if meeting.chapter_ids else 0
        meeting.estimated_time_minutes = max(5, chapter_count * 5)
        meeting.save(update_fields=["chapter_ids", "title", "meeting_index", "estimated_time_minutes"])
        out = MeetingSectionSerializer(meeting, context={"request": request})
        return Response(out.data)
    @action(detail=True, methods=["patch"], url_path="reorder")
    def reorder_meetings(self, request: Request, pk: int | None = None) -> Response:
        """Reorder meetings. Expects {meetings: [{id, meeting_index}, ...]}."""
        schedule = self.get_object()
        meetings_data = request.data.get("meetings", [])
        if not isinstance(meetings_data, list):
            return Response(
                {"error": "meetings must be a list."},
                status=status.HTTP_400_BAD_REQUEST,
            )
        meeting_map = {m.id: m for m in schedule.meetings.all()}
        updated: list[MeetingSection] = []
        for entry in meetings_data:
            mid = entry.get("id")
            new_index = entry.get("meeting_index")
            if mid is None or new_index is None:
                continue
            m = meeting_map.get(mid)
            if m is None:
                continue
            m.meeting_index = new_index
            updated.append(m)
        MeetingSection.objects.bulk_update(updated, ["meeting_index"])
        schedule.refresh_from_db()
        out = ReadingScheduleSerializer(schedule, context={"request": request})
        return Response(out.data)
@@ -0,0 +1,38 @@
 from django.contrib import admin
 from apps.groups.models import (
    GroupMeeting,
    GroupMembership,
    NotificationPreference,
    PaceNotification,
    ReadingGroup,
 )
@admin.register(ReadingGroup)
 class ReadingGroupAdmin(admin.ModelAdmin):
    list_display = ["name", "created_by", "created_at"]
    search_fields = ["name"]
@admin.register(GroupMembership)
 class GroupMembershipAdmin(admin.ModelAdmin):
    list_display = ["user", "group", "role", "joined_at"]
    list_filter = ["role"]
@admin.register(GroupMeeting)
 class GroupMeetingAdmin(admin.ModelAdmin):
    list_display = ["group", "title", "target_section_label", "scheduled_at"]
    list_filter = ["group"]
@admin.register(NotificationPreference)
 class NotificationPreferenceAdmin(admin.ModelAdmin):
    list_display = ["user", "pace_notifications_enabled", "reminder_enabled", "frequency"]
@admin.register(PaceNotification)
 class PaceNotificationAdmin(admin.ModelAdmin):
    list_display = ["user", "meeting", "status", "created_at"]
    list_filter = ["status"]
@@ -0,0 +1,8 @@
 from django.apps import AppConfig
 class GroupsConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "apps.groups"
    verbose_name = "Reading Groups"
    label = "groups"
@@ -0,0 +1,109 @@
 # Generated by Django 5.1.7 on 2026-06-20 19:22
 import django.db.models.deletion
 from django.conf import settings
 from django.db import migrations, models
 class Migration(migrations.Migration):
    initial = True
    dependencies = [
        ('books', '0003_readingprogress_epub_location'),
        ('users', '0001_initial'),
        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
    ]
    operations = [
        migrations.CreateModel(
            name='NotificationPreference',
            fields=[
                ('user', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, primary_key=True, related_name='notification_preference', serialize=False, to=settings.AUTH_USER_MODEL)),
                ('pace_notifications_enabled', models.BooleanField(default=True)),
                ('reminder_enabled', models.BooleanField(default=True)),
                ('frequency', models.CharField(choices=[('daily', 'Daily'), ('weekly', 'Weekly')], default='daily', max_length=16)),
                ('created_at', models.DateTimeField(auto_now_add=True)),
                ('updated_at', models.DateTimeField(auto_now=True)),
            ],
            options={
                'verbose_name': 'Notification Preference',
                'verbose_name_plural': 'Notification Preferences',
                'db_table': 'groups_notification_preference',
            },
        ),
        migrations.CreateModel(
            name='ReadingGroup',
            fields=[
                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
                ('name', models.CharField(db_index=True, max_length=256)),
                ('description', models.TextField(blank=True, default='')),
                ('created_at', models.DateTimeField(auto_now_add=True)),
                ('book', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='reading_groups', to='books.book')),
                ('created_by', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='created_groups', to=settings.AUTH_USER_MODEL)),
                ('ebook', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='reading_groups', to='books.ebook')),
            ],
            options={
                'verbose_name': 'Reading Group',
                'verbose_name_plural': 'Reading Groups',
                'db_table': 'groups_reading_group',
                'ordering': ['-created_at'],
            },
        ),
        migrations.CreateModel(
            name='GroupMeeting',
            fields=[
                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
                ('title', models.CharField(blank=True, default='', max_length=512)),
                ('scheduled_at', models.DateTimeField(db_index=True)),
                ('target_section', models.PositiveIntegerField(default=0, help_text='Target chapter/section index to reach by this meeting')),
                ('target_section_label', models.CharField(blank=True, default='', help_text="Human-readable label for the target section (e.g. 'Section 3')", max_length=512)),
                ('created_at', models.DateTimeField(auto_now_add=True)),
                ('group', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='meetings', to='groups.readinggroup')),
            ],
            options={
                'verbose_name': 'Group Meeting',
                'verbose_name_plural': 'Group Meetings',
                'db_table': 'groups_meeting',
                'ordering': ['scheduled_at'],
            },
        ),
        migrations.CreateModel(
            name='PaceNotification',
            fields=[
                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
                ('status', models.CharField(choices=[('pending', 'Pending'), ('sent', 'Sent'), ('dismissed', 'Dismissed')], default='pending', max_length=16)),
                ('current_section', models.PositiveIntegerField(default=0)),
                ('target_section', models.PositiveIntegerField(default=0)),
                ('ahead_behind_delta', models.IntegerField(default=0)),
                ('created_at', models.DateTimeField(auto_now_add=True)),
                ('ebook', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='pace_notifications', to='books.ebook')),
                ('meeting', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='pace_notifications', to='groups.groupmeeting')),
                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='pace_notifications', to=settings.AUTH_USER_MODEL)),
            ],
            options={
                'verbose_name': 'Pace Notification',
                'verbose_name_plural': 'Pace Notifications',
                'db_table': 'groups_pace_notification',
                'ordering': ['-created_at'],
                'indexes': [models.Index(fields=['user', 'meeting', 'ebook'], name='groups_pace_user_id_18e929_idx')],
            },
        ),
        migrations.CreateModel(
            name='GroupMembership',
            fields=[
                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
                ('role', models.CharField(choices=[('admin', 'Admin'), ('member', 'Member')], default='member', max_length=16)),
                ('joined_at', models.DateTimeField(auto_now_add=True)),
                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='group_memberships', to=settings.AUTH_USER_MODEL)),
                ('group', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='memberships', to='groups.readinggroup')),
            ],
            options={
                'verbose_name': 'Group Membership',
                'verbose_name_plural': 'Group Memberships',
                'db_table': 'groups_membership',
                'indexes': [models.Index(fields=['user', 'group'], name='groups_memb_user_id_9cda7e_idx')],
                'unique_together': {('user', 'group')},
            },
        ),
    ]
@@ -0,0 +1,190 @@
 from __future__ import annotations
 from django.conf import settings
 from django.db import models
 class FrequencyChoice(models.TextChoices):
    DAILY = "daily", "Daily"
    WEEKLY = "weekly", "Weekly"
 class MembershipRole(models.TextChoices):
    ADMIN = "admin", "Admin"
    MEMBER = "member", "Member"
 class NotificationStatus(models.TextChoices):
    PENDING = "pending", "Pending"
    SENT = "sent", "Sent"
    DISMISSED = "dismissed", "Dismissed"
 class ReadingGroup(models.Model):
    """A group of users reading a book together with scheduled meetings."""
    name = models.CharField(max_length=256, db_index=True)
    description = models.TextField(blank=True, default="")
    book = models.ForeignKey(
        "books.Book",
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="reading_groups",
    )
    ebook = models.ForeignKey(
        "books.EBook",
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="reading_groups",
    )
    created_by = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="created_groups",
    )
    created_at = models.DateTimeField(auto_now_add=True)
    class Meta:
        db_table = "groups_reading_group"
        verbose_name = "Reading Group"
        verbose_name_plural = "Reading Groups"
        ordering = ["-created_at"]
    def __str__(self) -> str:
        return self.name
 class GroupMembership(models.Model):
    """User membership in a reading group."""
    user = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="group_memberships",
    )
    group = models.ForeignKey(
        ReadingGroup,
        on_delete=models.CASCADE,
        related_name="memberships",
    )
    role = models.CharField(
        max_length=16,
        choices=MembershipRole.choices,
        default=MembershipRole.MEMBER,
    )
    joined_at = models.DateTimeField(auto_now_add=True)
    class Meta:
        db_table = "groups_membership"
        verbose_name = "Group Membership"
        verbose_name_plural = "Group Memberships"
        unique_together = [("user", "group")]
        indexes = [models.Index(fields=["user", "group"])]
    def __str__(self) -> str:
        return f"{self.user} in {self.group}"
 class GroupMeeting(models.Model):
    """A scheduled meeting for a reading group with a target section."""
    group = models.ForeignKey(
        ReadingGroup,
        on_delete=models.CASCADE,
        related_name="meetings",
    )
    title = models.CharField(max_length=512, blank=True, default="")
    scheduled_at = models.DateTimeField(db_index=True)
    target_section = models.PositiveIntegerField(
        default=0,
        help_text="Target chapter/section index to reach by this meeting",
    )
    target_section_label = models.CharField(
        max_length=512,
        blank=True,
        default="",
        help_text="Human-readable label for the target section (e.g. 'Section 3')",
    )
    created_at = models.DateTimeField(auto_now_add=True)
    class Meta:
        db_table = "groups_meeting"
        verbose_name = "Group Meeting"
        verbose_name_plural = "Group Meetings"
        ordering = ["scheduled_at"]
    def __str__(self) -> str:
        return f"{self.group.name} — {self.title or self.target_section_label} ({self.scheduled_at.date()})"
 class NotificationPreference(models.Model):
    """Per-user notification settings for reading pace alerts."""
    user = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="notification_preference",
        primary_key=True,
    )
    pace_notifications_enabled = models.BooleanField(default=True)
    reminder_enabled = models.BooleanField(default=True)
    frequency = models.CharField(
        max_length=16,
        choices=FrequencyChoice.choices,
        default=FrequencyChoice.DAILY,
    )
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    class Meta:
        db_table = "groups_notification_preference"
        verbose_name = "Notification Preference"
        verbose_name_plural = "Notification Preferences"
    def __str__(self) -> str:
        return f"{self.user} — pace={'on' if self.pace_notifications_enabled else 'off'}, freq={self.frequency}"
 class PaceNotification(models.Model):
    """Tracks reading pace notifications sent to users to avoid duplicates."""
    user = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="pace_notifications",
    )
    meeting = models.ForeignKey(
        GroupMeeting,
        on_delete=models.CASCADE,
        related_name="pace_notifications",
    )
    ebook = models.ForeignKey(
        "books.EBook",
        on_delete=models.CASCADE,
        related_name="pace_notifications",
        null=True,
        blank=True,
    )
    status = models.CharField(
        max_length=16,
        choices=NotificationStatus.choices,
        default=NotificationStatus.PENDING,
    )
    current_section = models.PositiveIntegerField(default=0)
    target_section = models.PositiveIntegerField(default=0)
    ahead_behind_delta = models.IntegerField(default=0)
    created_at = models.DateTimeField(auto_now_add=True)
    class Meta:
        db_table = "groups_pace_notification"
        verbose_name = "Pace Notification"
        verbose_name_plural = "Pace Notifications"
        ordering = ["-created_at"]
        indexes = [
            models.Index(fields=["user", "meeting", "ebook"]),
        ]
    def __str__(self) -> str:
        return f"{self.user} — meeting {self.meeting_id}: {self.get_status_display()}"
@@ -0,0 +1,137 @@
 from __future__ import annotations
 from rest_framework import serializers
 from apps.groups.models import (
    FrequencyChoice,
    GroupMeeting,
    GroupMembership,
    NotificationPreference,
    PaceNotification,
    ReadingGroup,
 )
 from apps.groups.services.pace import PaceStatus
 class NotificationPreferenceSerializer(serializers.ModelSerializer):
    class Meta:
        model = NotificationPreference
        fields = [
            "pace_notifications_enabled",
            "reminder_enabled",
            "frequency",
        ]
    def validate_frequency(self, value: str) -> str:
        valid = {choice[0] for choice in FrequencyChoice.choices}
        if value not in valid:
            raise serializers.ValidationError(
                f"Frequency must be one of: {', '.join(valid)}"
            )
        return value
 class GroupMeetingSerializer(serializers.ModelSerializer):
    group_name = serializers.CharField(source="group.name", read_only=True)
    class Meta:
        model = GroupMeeting
        fields = [
            "id",
            "group",
            "group_name",
            "title",
            "scheduled_at",
            "target_section",
            "target_section_label",
            "created_at",
        ]
        read_only_fields = ["id", "created_at"]
    def validate_target_section(self, value: int) -> int:
        if value < 0:
            raise serializers.ValidationError("Target section must be non-negative.")
        return value
 class ReadingGroupSerializer(serializers.ModelSerializer):
    member_count = serializers.SerializerMethodField()
    meeting_count = serializers.SerializerMethodField()
    class Meta:
        model = ReadingGroup
        fields = [
            "id",
            "name",
            "description",
            "book",
            "ebook",
            "created_by",
            "created_at",
            "member_count",
            "meeting_count",
        ]
        read_only_fields = ["id", "created_by", "created_at"]
    def get_member_count(self, obj: ReadingGroup) -> int:
        return obj.memberships.count()
    def get_meeting_count(self, obj: ReadingGroup) -> int:
        return obj.meetings.count()
 class GroupMembershipSerializer(serializers.ModelSerializer):
    user_email = serializers.CharField(source="user.email", read_only=True)
    group_name = serializers.CharField(source="group.name", read_only=True)
    class Meta:
        model = GroupMembership
        fields = ["id", "user", "user_email", "group", "group_name", "role", "joined_at"]
        read_only_fields = ["id", "joined_at"]
 class PaceNotificationSerializer(serializers.ModelSerializer):
    status_display = serializers.CharField(source="get_status_display", read_only=True)
    class Meta:
        model = PaceNotification
        fields = [
            "id",
            "user",
            "meeting",
            "ebook",
            "status",
            "status_display",
            "current_section",
            "target_section",
            "ahead_behind_delta",
            "created_at",
        ]
        read_only_fields = ["id", "created_at"]
 class PaceStatusSerializer(serializers.Serializer):
    meeting_id = serializers.IntegerField()
    meeting_title = serializers.CharField()
    scheduled_at = serializers.CharField()
    target_section = serializers.IntegerField()
    target_section_label = serializers.CharField()
    current_section = serializers.IntegerField()
    ahead_behind_delta = serializers.IntegerField()
    status = serializers.CharField()
    days_until_meeting = serializers.IntegerField()
    sections_to_catch_up = serializers.IntegerField()
    ebook_id = serializers.IntegerField()
    ebook_title = serializers.CharField()
 class ReminderSerializer(serializers.Serializer):
    meeting_id = serializers.IntegerField()
    meeting_title = serializers.CharField()
    scheduled_at = serializers.CharField()
    target_section = serializers.IntegerField()
    target_section_label = serializers.CharField()
    group_name = serializers.CharField()
    hours_until = serializers.IntegerField()
    ebook_id = serializers.IntegerField()
    ebook_title = serializers.CharField()
@@ -0,0 +1,219 @@
 """Pace calculation service for reading progress vs meeting targets."""
 from __future__ import annotations
 import logging
 from datetime import datetime, timedelta
 from typing import TypedDict
 from django.db.models import QuerySet
 from django.utils import timezone
 from apps.books.models import EBook, ReadingProgress
 from apps.groups.models import (
    GroupMeeting,
    GroupMembership,
    NotificationPreference,
    PaceNotification,
    NotificationStatus,
 )
 logger = logging.getLogger(__name__)
 class PaceStatus(TypedDict):
    meeting_id: int
    meeting_title: str
    scheduled_at: str
    target_section: int
    target_section_label: str
    current_section: int
    ahead_behind_delta: int
    status: str  # "ahead", "behind", "on_track", "completed"
    days_until_meeting: int
    sections_to_catch_up: int
    ebook_id: int
    ebook_title: str
 def get_relevant_ebooks_for_user(user) -> QuerySet[EBook]:
    """Return ebooks that belong to groups the user is a member of."""
    group_ids = (
        GroupMembership.objects.filter(user=user)
        .values_list("group_id", flat=True)
    )
    return (
        EBook.objects.filter(reading_groups__in=group_ids)
        .select_related("reading_progress")
        .prefetch_related("chapters")
        .distinct()
    )
 def calculate_pace(
    user,
    ebook: EBook | None = None,
    meeting: GroupMeeting | None = None,
 ) -> list[PaceStatus]:
    """Calculate reading pace for a user's upcoming meetings.
    Compares the user's current reading progress (chapter index) against
    the target section for each upcoming meeting within 3 days.
    """
    now = timezone.now()
    three_days_from_now = now + timedelta(days=3)
    # Find upcoming meetings for groups the user belongs to
    user_group_ids = (
        GroupMembership.objects.filter(user=user)
        .values_list("group_id", flat=True)
    )
    meetings_qs = GroupMeeting.objects.filter(
        group_id__in=user_group_ids,
        scheduled_at__gte=now,
        scheduled_at__lte=three_days_from_now,
    ).select_related("group", "group__ebook")
    if meeting:
        meetings_qs = meetings_qs.filter(pk=meeting.pk)
    meetings = list(meetings_qs)
    results: list[PaceStatus] = []
    for m in meetings:
        group_ebook = m.group.ebook
        ebooks_to_check: list[EBook] = []
        if ebook:
            ebooks_to_check = [ebook]
        elif group_ebook:
            ebooks_to_check = [group_ebook]
        else:
            # Check all ebooks in the group
            ebooks_to_check = list(
                EBook.objects.filter(reading_groups=m.group)
                .select_related("reading_progress")
                .prefetch_related("chapters")
            )
        for eb in ebooks_to_check:
            pace = _compute_single_pace(user, m, eb, now)
            if pace:
                results.append(pace)
    return results
 def _compute_single_pace(
    user,
    meeting: GroupMeeting,
    ebook: EBook,
    now: datetime,
 ) -> PaceStatus | None:
    """Compute pace for one user + meeting + ebook combination."""
    try:
        progress = ebook.reading_progress
    except ReadingProgress.DoesNotExist:
        # No progress yet — user hasn't started reading
        return None
    # Current section: based on last_page (chapter index) or computed from progress %
    if progress.last_page > 0:
        current_section = progress.last_page
    elif progress.current_position > 0:
        chapter_count = ebook.chapters.count() or ebook.page_count or 1
        current_section = max(1, int((progress.current_position / 100) * chapter_count))
    else:
        current_section = 0
    target_section = meeting.target_section or 0
    if target_section == 0:
        return None
    delta = current_section - target_section
    days_until = max(0, (meeting.scheduled_at - now).days)
    if current_section >= target_section:
        if current_section >= target_section and progress.current_position > 0:
            status = "completed"
        else:
            status = "ahead"
    elif delta >= -1:
        status = "on_track"
    else:
        status = "behind"
    return PaceStatus(
        meeting_id=meeting.pk,
        meeting_title=meeting.title or meeting.target_section_label,
        scheduled_at=meeting.scheduled_at.isoformat(),
        target_section=target_section,
        target_section_label=meeting.target_section_label,
        current_section=current_section,
        ahead_behind_delta=delta,
        status=status,
        days_until_meeting=days_until,
        sections_to_catch_up=max(0, target_section - current_section),
        ebook_id=ebook.pk,
        ebook_title=ebook.title,
    )
 def should_send_notification(
    user,
    meeting: GroupMeeting,
    ebook: EBook,
 ) -> bool:
    """Check if a pace notification should be sent based on user preferences."""
    pref, _ = NotificationPreference.objects.get_or_create(user=user)
    if not pref.pace_notifications_enabled:
        return False
    # Check if notification was already sent today
    today = timezone.now().date()
    existing = PaceNotification.objects.filter(
        user=user,
        meeting=meeting,
        ebook=ebook,
        created_at__date=today,
    ).exclude(status=NotificationStatus.DISMISSED)
    if existing.exists():
        return False
    # Frequency check
    if pref.frequency == "weekly":
        week_ago = today - timedelta(days=7)
        recent = PaceNotification.objects.filter(
            user=user,
            meeting=meeting,
            ebook=ebook,
            created_at__date__gte=week_ago,
        ).exclude(status=NotificationStatus.DISMISSED)
        if recent.exists():
            return False
    return True
 def get_reminder_meetings(user) -> list[GroupMeeting]:
    """Get meetings that are within 24 hours for reminder notifications."""
    now = timezone.now()
    tomorrow = now + timedelta(days=1)
    user_group_ids = (
        GroupMembership.objects.filter(user=user)
        .values_list("group_id", flat=True)
    )
    return list(
        GroupMeeting.objects.filter(
            group_id__in=user_group_ids,
            scheduled_at__gte=now,
            scheduled_at__lte=tomorrow,
        )
        .select_related("group", "group__ebook")
        .order_by("scheduled_at")
    )
@@ -0,0 +1,23 @@
 from django.urls import include, path
 from rest_framework.routers import DefaultRouter
 from apps.groups.views import (
    GroupMeetingViewSet,
    ReadingGroupViewSet,
    dismiss_pace_notification_view,
    notification_preferences_view,
    pace_status_view,
    reminder_view,
 )
 router = DefaultRouter()
 router.register(r"groups", ReadingGroupViewSet, basename="reading-group")
 router.register(r"meetings", GroupMeetingViewSet, basename="group-meeting")
 urlpatterns = [
    path("", include(router.urls)),
    path("notifications/preferences/", notification_preferences_view, name="notification-preferences"),
    path("notifications/pace/", pace_status_view, name="pace-status"),
    path("notifications/dismiss/", dismiss_pace_notification_view, name="dismiss-pace"),
    path("notifications/reminders/", reminder_view, name="meeting-reminders"),
 ]
@@ -0,0 +1,207 @@
 from __future__ import annotations
 from django.db.models import QuerySet
 from rest_framework import permissions, status, viewsets
 from rest_framework.decorators import action, api_view, permission_classes
 from rest_framework.permissions import IsAuthenticated
 from rest_framework.request import Request
 from rest_framework.response import Response
 from apps.books.models import EBook
 from apps.groups.models import (
    GroupMeeting,
    GroupMembership,
    NotificationPreference,
    PaceNotification,
    NotificationStatus,
    ReadingGroup,
 )
 from apps.groups.serializers import (
    GroupMeetingSerializer,
    GroupMembershipSerializer,
    NotificationPreferenceSerializer,
    PaceNotificationSerializer,
    PaceStatusSerializer,
    ReadingGroupSerializer,
    ReminderSerializer,
 )
 from apps.groups.services.pace import (
    calculate_pace,
    get_reminder_meetings,
    should_send_notification,
 )
 class IsGroupMember(permissions.BasePermission):
    """Only allow group members to access group resources."""
    def has_object_permission(self, request: Request, view: object, obj: ReadingGroup) -> bool:
        return obj.memberships.filter(user=request.user).exists()
 class ReadingGroupViewSet(viewsets.ModelViewSet):
    permission_classes = [IsAuthenticated, IsGroupMember]
    serializer_class = ReadingGroupSerializer
    def get_queryset(self) -> QuerySet[ReadingGroup]:
        return (
            ReadingGroup.objects.filter(memberships__user=self.request.user)
            .prefetch_related("memberships", "meetings")
            .distinct()
        )
    def perform_create(self, serializer) -> None:
        group = serializer.save(created_by=self.request.user)
        GroupMembership.objects.create(
            user=self.request.user,
            group=group,
            role="admin",
        )
    @action(detail=False, methods=["get"], url_path="all")
    def all_groups(self, request: Request) -> Response:
        """Return all groups (for discovery)."""
        qs = ReadingGroup.objects.all().prefetch_related("memberships", "meetings")
        page = self.paginate_queryset(qs)
        if page is not None:
            serializer = self.get_serializer(page, many=True)
            return self.get_paginated_response(serializer.data)
        serializer = self.get_serializer(qs, many=True)
        return Response(serializer.data)
 class GroupMeetingViewSet(viewsets.ModelViewSet):
    permission_classes = [IsAuthenticated]
    serializer_class = GroupMeetingSerializer
    def get_queryset(self) -> QuerySet[GroupMeeting]:
        user_group_ids = (
            GroupMembership.objects.filter(user=self.request.user)
            .values_list("group_id", flat=True)
        )
        return GroupMeeting.objects.filter(group_id__in=user_group_ids).select_related(
            "group"
        )
    def perform_create(self, serializer) -> None:
        group = serializer.validated_data["group"]
        if not group.memberships.filter(user=self.request.user).exists():
            raise permissions.PermissionDenied("You must be a group member to create meetings.")
        serializer.save()
    @action(detail=False, methods=["get"], url_path="upcoming")
    def upcoming(self, request: Request) -> Response:
        """Return upcoming meetings for the user's groups (within 3 days)."""
        from django.utils import timezone
        from datetime import timedelta
        now = timezone.now()
        three_days = now + timedelta(days=3)
        qs = self.get_queryset().filter(
            scheduled_at__gte=now,
            scheduled_at__lte=three_days,
        )
        serializer = self.get_serializer(qs, many=True)
        return Response(serializer.data)
@api_view(["GET", "PATCH"])
@permission_classes([IsAuthenticated])
 def notification_preferences_view(request: Request) -> Response:
    """Get or update notification preferences for the current user."""
    pref, _created = NotificationPreference.objects.get_or_create(user=request.user)
    if request.method == "GET":
        serializer = NotificationPreferenceSerializer(pref)
        return Response(serializer.data)
    serializer = NotificationPreferenceSerializer(pref, data=request.data, partial=True)
    serializer.is_valid(raise_exception=True)
    serializer.save()
    return Response(serializer.data)
@api_view(["GET"])
@permission_classes([IsAuthenticated])
 def pace_status_view(request: Request) -> Response:
    """Get reading pace status for the current user's upcoming meetings."""
    ebook_id = request.query_params.get("ebook_id")
    ebook: EBook | None = None
    if ebook_id:
        try:
            ebook = EBook.objects.select_related("reading_progress").prefetch_related("chapters").get(
                pk=ebook_id, user=request.user
            )
        except EBook.DoesNotExist:
            return Response(
                {"error": "EBook not found."}, status=status.HTTP_404_NOT_FOUND
            )
    pace_data = calculate_pace(request.user, ebook=ebook)
    serializer = PaceStatusSerializer(pace_data, many=True)
    return Response(serializer.data)
@api_view(["POST"])
@permission_classes([IsAuthenticated])
 def dismiss_pace_notification_view(request: Request) -> Response:
    """Dismiss a pace notification so it won't show again."""
    meeting_id = request.data.get("meeting_id")
    ebook_id = request.data.get("ebook_id")
    if not meeting_id or not ebook_id:
        return Response(
            {"error": "meeting_id and ebook_id are required."},
            status=status.HTTP_400_BAD_REQUEST,
        )
    PaceNotification.objects.filter(
        user=request.user,
        meeting_id=meeting_id,
        ebook_id=ebook_id,
        status=NotificationStatus.PENDING,
    ).update(status=NotificationStatus.DISMISSED)
    return Response({"status": "dismissed"})
@api_view(["GET"])
@permission_classes([IsAuthenticated])
 def reminder_view(request: Request) -> Response:
    """Get pre-meeting reminders for meetings within 24 hours."""
    pref, _ = NotificationPreference.objects.get_or_create(user=request.user)
    if not pref.reminder_enabled:
        return Response([])
    meetings = get_reminder_meetings(request.user)
    now_dt = __import__("django").utils.timezone.now()
    reminders = []
    for mtg in meetings:
        group_ebook = mtg.group.ebook
        ebook: EBook | None = group_ebook
        if not ebook:
            ebooks = list(
                EBook.objects.filter(reading_groups=mtg.group).select_related("reading_progress")[:1]
            )
            ebook = ebooks[0] if ebooks else None
        if not ebook:
            continue
        hours_until = max(0, int((mtg.scheduled_at - now_dt).total_seconds() / 3600))
        reminders.append({
            "meeting_id": mtg.pk,
            "meeting_title": mtg.title or mtg.target_section_label,
            "scheduled_at": mtg.scheduled_at.isoformat(),
            "target_section": mtg.target_section,
            "target_section_label": mtg.target_section_label,
            "group_name": mtg.group.name,
            "hours_until": hours_until,
            "ebook_id": ebook.pk,
            "ebook_title": ebook.title,
        })
    serializer = ReminderSerializer(reminders, many=True)
    return Response(serializer.data)
@@ -41,6 +41,7 @@ INSTALLED_APPS = [
    "apps.books",
    "apps.annotations",
    "apps.reader",
    "apps.groups",
 ]
 MIDDLEWARE = [
@@ -8,6 +8,7 @@ urlpatterns = [
    path("api/books/", include("apps.books.urls")),
    path("api/annotations/", include("apps.annotations.urls")),
    path("api/reader/", include("apps.reader.urls")),
    path("api/groups/", include("apps.groups.urls")),
 ]
 if settings.DEBUG:
@@ -12,7 +12,6 @@ const AddBookPage = lazy(() => import("./pages/AddBook").then((m) => ({ default:
 const SettingsPage = lazy(() => import("./pages/Settings").then((m) => ({ default: m.SettingsPage })));
 const BookmarksNotesPage = lazy(() => import("./components/annotations/BookmarksNotesPage").then((m) => ({ default: m.BookmarksNotesPage })));
 const ReadingPage = lazy(() => import("./pages/ReadingPage").then((m) => ({ default: m.default })));
 const RecommendationPage = lazy(() => import("./pages/RecommendationPage").then((m) => ({ default: m.RecommendationPage })));
 const AuthPage = lazy(() => import("./pages/AuthPage"));
@@ -41,7 +40,6 @@ function AppRoutes() {
        <Route path="/auth" element={isAuthenticated ? <Navigate to="/" replace /> : <AuthPage />} />
        <Route path="/" element={<ProtectedRoute><LibraryPage /></ProtectedRoute>} />
        <Route path="/books/:id" element={<ProtectedRoute><BookDetailPage /></ProtectedRoute>} />
        <Route path="/books/:ebookId/schedule" element={<ProtectedRoute><RecommendationPage /></ProtectedRoute>} />
        <Route path="/read/:id" element={<ProtectedRoute><ReadingPage /></ProtectedRoute>} />
        <Route path="/reader/:id" element={<ProtectedRoute><ReaderRedirect /></ProtectedRoute>} />
        <Route path="/add" element={<ProtectedRoute><AddBookPage /></ProtectedRoute>} />
@@ -6,9 +6,7 @@ import type {
  ContentResponse,
  EBookDetail,
  EBookListItem,
  GenerateRecommendationsRequest,
  ReadingProgress,
  ReadingSchedule,
  ReadingSettings,
  TocResponse,
 } from "../types/book";
@@ -134,64 +132,3 @@ export const booksApi = {
    return data;
  },
 };
 export const schedulesApi = {
  async getSchedules(): Promise<ReadingSchedule[]> {
    const { data } = await api.get<ReadingSchedule[]>("/books/schedules/");
    return data;
  },
  async getSchedule(id: number): Promise<ReadingSchedule> {
    const { data } = await api.get<ReadingSchedule>(`/books/schedules/${id}/`);
    return data;
  },
  async generateRecommendations(request: GenerateRecommendationsRequest): Promise<ReadingSchedule> {
    const { data } = await api.post<ReadingSchedule>("/books/schedules/", {
      ebook_id: request.ebook_id,
      meeting_count: request.meeting_count ?? 4,
    });
    return data;
  },
  async regenerateRecommendations(scheduleId: number, meetingCount?: number): Promise<ReadingSchedule> {
    const { data } = await api.post<ReadingSchedule>(`/books/schedules/${scheduleId}/generate/`, {
      meeting_count: meetingCount ?? 4,
    });
    return data;
  },
  async confirmSchedule(scheduleId: number): Promise<ReadingSchedule> {
    const { data } = await api.post<ReadingSchedule>(`/books/schedules/${scheduleId}/confirm/`, {
      confirm: true,
    });
    return data;
  },
  async updateMeeting(
    scheduleId: number,
    meetingId: number,
    update: { chapter_ids?: number[]; title?: string; meeting_index?: number },
  ): Promise<unknown> {
    const { data } = await api.patch(
      `/books/schedules/${scheduleId}/meetings/${meetingId}/`,
      update,
    );
    return data;
  },
  async reorderMeetings(
    scheduleId: number,
    meetings: { id: number; meeting_index: number }[],
  ): Promise<ReadingSchedule> {
    const { data } = await api.patch<ReadingSchedule>(
      `/books/schedules/${scheduleId}/reorder/`,
      { meetings },
    );
    return data;
  },
  async deleteSchedule(id: number): Promise<void> {
    await api.delete(`/books/schedules/${id}/`);
  },
 };
@@ -0,0 +1,57 @@
 import api from "./client";
 import type {
  GroupMeeting,
  MeetingReminder,
  NotificationPreferences,
  PaceStatus,
  ReadingGroup,
 } from "../types/notifications";
 export const groupsApi = {
  async getPaceStatus(ebookId?: number): Promise<PaceStatus[]> {
    const params: Record<string, string> = {};
    if (ebookId) params.ebook_id = String(ebookId);
    const { data } = await api.get<PaceStatus[]>("/groups/notifications/pace/", { params });
    return data;
  },
  async getPreferences(): Promise<NotificationPreferences> {
    const { data } = await api.get<NotificationPreferences>("/groups/notifications/preferences/");
    return data;
  },
  async updatePreferences(
    prefs: Partial<NotificationPreferences>,
  ): Promise<NotificationPreferences> {
    const { data } = await api.patch<NotificationPreferences>(
      "/groups/notifications/preferences/",
      prefs,
    );
    return data;
  },
  async dismissPaceNotification(meetingId: number, ebookId: number): Promise<void> {
    await api.post("/groups/notifications/dismiss/", {
      meeting_id: meetingId,
      ebook_id: ebookId,
    });
  },
  async getReminders(): Promise<MeetingReminder[]> {
    const { data } = await api.get<MeetingReminder[]>("/groups/notifications/reminders/");
    return data;
  },
  async getGroups(): Promise<ReadingGroup[]> {
    const { data } = await api.get<{ count: number; results: ReadingGroup[] } | ReadingGroup[]>(
      "/groups/groups/",
    );
    if (Array.isArray(data)) return data;
    return data.results ?? [];
  },
  async getUpcomingMeetings(): Promise<GroupMeeting[]> {
    const { data } = await api.get<GroupMeeting[]>("/groups/meetings/upcoming/");
    return data;
  },
 };
@@ -1,5 +1,4 @@
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18n-lite";
 import { booksApi } from "../api/books";
 import { getApiErrorMessage } from "../api/errors";
@@ -47,7 +46,6 @@ export function BookContextMenu({
  const { t, language } = useTranslation();
  const locale = language as SupportedLanguage;
  const { showToast } = useToast();
  const navigate = useNavigate();
  const menuRef = useRef<HTMLDivElement>(null);
  const [position, setPosition] = useState({ left: x, top: y });
  const [activeAction, setActiveAction] = useState<ActionKind>(null);
@@ -150,18 +148,6 @@ export function BookContextMenu({
      >
        {activeAction === "sync" ? t("contextMenu.syncingMetadata") : t("contextMenu.syncMetadata")}
      </button>
      <button
        type="button"
        className={styles.item}
        role="menuitem"
        disabled={busy}
        onClick={() => {
          navigate(`/books/${book.id}/schedule`);
          onClose();
        }}
      >
        📅 Schedule Reading
      </button>
      <div className={styles.separator} role="separator" />
      <button
        type="button"
@@ -0,0 +1,119 @@
 import { useEffect, useState } from "react";
 import { useTranslation } from "react-i18n-lite";
 import { groupsApi } from "../api/groups";
 import type { PaceStatus } from "../types/notifications";
 interface PaceNotificationProps {
  ebookId?: number;
 }
 export function PaceNotification({ ebookId }: PaceNotificationProps) {
  const { t } = useTranslation();
  const [paceItems, setPaceItems] = useState<PaceStatus[]>([]);
  const [loading, setLoading] = useState(true);
  const [dismissed, setDismissed] = useState<Set<string>>(new Set());
  useEffect(() => {
    const load = async () => {
      try {
        const data = await groupsApi.getPaceStatus(ebookId);
        setPaceItems(data);
      } catch {
        // Silently fail — notifications are non-critical
      } finally {
        setLoading(false);
      }
    };
    void load();
  }, [ebookId]);
  const handleDismiss = async (meetingId: number, itemEbookId: number) => {
    const key = `${meetingId}-${itemEbookId}`;
    setDismissed((prev) => new Set(prev).add(key));
    try {
      await groupsApi.dismissPaceNotification(meetingId, itemEbookId);
    } catch {
      // Best effort dismissal
    }
  };
  if (loading || paceItems.length === 0) return null;
  const visibleItems = paceItems.filter(
    (p) => !dismissed.has(`${p.meeting_id}-${p.ebook_id}`),
  );
  if (visibleItems.length === 0) return null;
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, padding: "12px 0" }}>
      {visibleItems.map((item) => {
        const isBehind = item.status === "behind";
        const isAhead = item.status === "ahead" || item.status === "completed";
        const isOnTrack = item.status === "on_track";
        const bgColor = isBehind ? "#fde8e8" : isAhead ? "#d4edda" : "#e8f4fd";
        const borderColor = isBehind ? "#e74c3c" : isAhead ? "#27ae60" : "#3498db";
        const textColor = isBehind ? "#a71d2a" : isAhead ? "#155724" : "#0c5460";
        return (
          <div
            key={`${item.meeting_id}-${item.ebook_id}`}
            style={{
              background: bgColor,
              border: `1px solid ${borderColor}`,
              borderRadius: 8,
              padding: "12px 16px",
              display: "flex",
              alignItems: "flex-start",
              justifyContent: "space-between",
              gap: 12,
            }}
          >
            <div style={{ flex: 1 }}>
              <div style={{ fontSize: 14, fontWeight: 600, color: textColor, marginBottom: 4 }}>
                {isBehind
                  ? `Behind schedule — catch up ${item.sections_to_catch_up} section${item.sections_to_catch_up !== 1 ? "s" : ""}`
                  : isOnTrack
                    ? "On track — keep going!"
                    : item.status === "completed"
                      ? "Meeting target completed!"
                      : "Ahead of schedule — great job!"}
              </div>
              <div style={{ fontSize: 13, color: textColor, opacity: 0.85 }}>
                {item.meeting_title || `Target: ${item.target_section_label || `Section ${item.target_section}`}`}
                {" — "}
                {item.ebook_title}
              </div>
              <div style={{ fontSize: 12, color: textColor, opacity: 0.7, marginTop: 2 }}>
                {isBehind
                  ? `Currently at section ${item.current_section}, need section ${item.target_section}`
                  : `Section ${item.current_section} of ${item.target_section}`}
                {item.days_until_meeting > 0 &&
                  ` · ${item.days_until_meeting} day${item.days_until_meeting !== 1 ? "s" : ""} until meeting`}
                {item.days_until_meeting === 0 && " · Meeting today"}
              </div>
            </div>
            <button
              type="button"
              onClick={() => handleDismiss(item.meeting_id, item.ebook_id)}
              style={{
                background: "none",
                border: "none",
                color: textColor,
                fontSize: 20,
                cursor: "pointer",
                padding: "0 4px",
                lineHeight: 1,
                opacity: 0.6,
                flexShrink: 0,
              }}
              title="Dismiss"
            >
              ×
            </button>
          </div>
        );
      })}
    </div>
  );
 }
@@ -0,0 +1,71 @@
 import { useEffect, useState } from "react";
 import { groupsApi } from "../../api/groups";
 import type { PaceStatus } from "../../types/notifications";
 interface ReadingPaceBannerProps {
  ebookId: number;
  currentSection: number;
 }
 export function ReadingPaceBanner({ ebookId, currentSection }: ReadingPaceBannerProps) {
  const [paceItems, setPaceItems] = useState<PaceStatus[]>([]);
  useEffect(() => {
    const load = async () => {
      try {
        const data = await groupsApi.getPaceStatus(ebookId);
        setPaceItems(data);
      } catch {
        // Silently fail
      }
    };
    void load();
  }, [ebookId, currentSection]);
  if (paceItems.length === 0) return null;
  // Only show if user is one section away from target
  const relevantItems = paceItems.filter(
    (p) => Math.abs(p.target_section - p.current_section) <= 1 && p.status !== "completed",
  );
  if (relevantItems.length === 0) return null;
  return (
    <div
      style={{
        background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
        color: "#fff",
        padding: "10px 16px",
        fontSize: 13,
        fontWeight: 500,
        textAlign: "center",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        gap: 8,
        flexWrap: "wrap",
        position: "sticky",
        top: 0,
        zIndex: 10,
      }}
    >
      {relevantItems.map((item) => {
        const isAlmostThere = item.sections_to_catch_up === 1;
        const isAtTarget = item.sections_to_catch_up === 0;
        return (
          <span key={item.meeting_id}>
            {isAtTarget
              ? `You've reached the target for ${item.meeting_title || `Section ${item.target_section}`}!`
              : isAlmostThere
                ? `Almost there! Just 1 section to go for ${item.meeting_title || `Section ${item.target_section}`}.`
                : `You should be on ${item.target_section_label || `Section ${item.target_section}`} by the upcoming meeting.`}
            {item.days_until_meeting > 0 &&
              ` (${item.days_until_meeting} day${item.days_until_meeting !== 1 ? "s" : ""} left)`}
          </span>
        );
      })}
    </div>
  );
 }
@@ -22,6 +22,7 @@ import { SelectionPopover } from "./SelectionPopover";
 import { BookMarkersPanel } from "./BookMarkersPanel";
 import { BookmarkReaderRail } from "./BookmarkReaderRail";
 import { ResumeReadingButton } from "./ResumeReadingButton";
 import { ReadingPaceBanner } from "../notifications/ReadingPaceBanner";
 import type { MarkerEntry } from "@/types";
 const ReaderToolbar = lazy(() => import("./ReaderToolbar"));
@@ -130,6 +131,10 @@ export function EpubReadingView({ book, bookId, initialEpubLocation }: EpubReadi
  return (
    <ReaderSuspenseShell theme={settings.theme}>
        <ReadingPaceBanner
          ebookId={bookId}
          currentSection={tocItems.length > 0 ? Math.max(1, Math.ceil((progress / 100) * tocItems.length)) : 0}
        />
        <ReaderToolbar
          bookTitle={book.title}
          chapterTitle={chapterTitle || t("reader.reading")}
@@ -24,6 +24,7 @@ import { BookmarkReaderRail } from "./BookmarkReaderRail";
 import { ResumeReadingButton } from "./ResumeReadingButton";
 import { PdfLimitationsNotice } from "./PdfLimitationsNotice";
 import { PdfViewer } from "./PdfViewer";
 import { ReadingPaceBanner } from "../notifications/ReadingPaceBanner";
 import type { MarkerEntry } from "@/types";
 const ReaderToolbar = lazy(() => import("./ReaderToolbar"));
@@ -170,6 +171,10 @@ export function PdfReadingView({ book, bookId, initialAnchor }: PdfReadingViewPr
  return (
    <ReaderSuspenseShell theme={settings.theme}>
        <ReadingPaceBanner
          ebookId={bookId}
          currentSection={currentPage}
        />
        <ReaderToolbar
          bookTitle={book.title}
          chapterTitle={chapterTitle || t("reader.reading")}
@@ -19,6 +19,7 @@ import { useVoiceSearch } from "../hooks/useVoiceSearch";
 import { useMediaQuery, BREAKPOINTS } from "../hooks/useMediaQuery";
 import { SearchSuggestions } from "../components/search/SearchSuggestions";
 import { BookContextMenu } from "../components/BookContextMenu";
 import { PaceNotification } from "../components/notifications/PaceNotification";
 interface FilterState {
  genre: string;
@@ -256,6 +257,9 @@ export function LibraryPage() {
        </div>
      </header>
      {/* Pace Notifications */}
      <PaceNotification />
      {/* Search Bar */}
      <div style={{ marginBottom: 16 }}>
        <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
@@ -1,601 +0,0 @@
 import React, { useCallback, useEffect, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
 import { useTranslation } from "react-i18n-lite";
 import { schedulesApi } from "../api/books";
 import { booksApi } from "../api/books";
 import type {
  BookChapter,
  EBookListItem,
  MeetingSection,
  ReadingSchedule,
 } from "../types/book";
 import { useMediaQuery, BREAKPOINTS } from "../hooks/useMediaQuery";
 /* ---- drag-and-drop types ---- */
 interface DragData {
  chapterId: number;
  sourceMeetingId: number | null; // null = unassigned
 }
 function formatTime(minutes: number): string {
  if (minutes < 60) return `${minutes} min`;
  const h = Math.floor(minutes / 60);
  const m = minutes % 60;
  return m > 0 ? `${h}h ${m}m` : `${h}h`;
 }
 export function RecommendationPage() {
  const { t } = useTranslation();
  const { ebookId } = useParams<{ ebookId: string }>();
  const navigate = useNavigate();
  const isMobile = useMediaQuery(BREAKPOINTS.md);
  const [ebook, setEbook] = useState<EBookListItem | null>(null);
  const [schedule, setSchedule] = useState<ReadingSchedule | null>(null);
  const [loading, setLoading] = useState(true);
  const [generating, setGenerating] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [draggedChapter, setDraggedChapter] = useState<DragData | null>(null);
  const [dropTarget, setDropTarget] = useState<number | null>(null);
  const bookId = Number(ebookId);
  const validId = !Number.isNaN(bookId);
  const loadData = useCallback(async () => {
    if (!validId) {
      setError("Invalid ebook ID.");
      setLoading(false);
      return;
    }
    setLoading(true);
    setError(null);
    try {
      const [ebookData, schedules] = await Promise.all([
        booksApi.getEBook(bookId),
        schedulesApi.getSchedules(),
      ]);
      setEbook({
        id: ebookData.id,
        title: ebookData.title,
        author: ebookData.author,
        filename: ebookData.filename,
        format: ebookData.format,
        page_count: ebookData.page_count,
        cover_image:
          typeof ebookData.cover_image === "string" ? ebookData.cover_image : null,
        created_at: ebookData.created_at,
        progress: ebookData.progress?.current_position ?? null,
        started: ebookData.progress != null,
      });
      const existing = schedules.find((s) => s.ebook === bookId);
      setSchedule(existing ?? null);
    } catch (err) {
      setError(err instanceof Error ? err.message : "Failed to load data.");
    } finally {
      setLoading(false);
    }
  }, [bookId, validId]);
  useEffect(() => {
    void loadData();
  }, [loadData]);
  const handleGenerate = useCallback(async () => {
    if (!validId) return;
    setGenerating(true);
    setError(null);
    try {
      const newSchedule = await schedulesApi.generateRecommendations({
        ebook_id: bookId,
        meeting_count: 4,
      });
      setSchedule(newSchedule);
    } catch (err) {
      setError(err instanceof Error ? err.message : "Failed to generate recommendations.");
    } finally {
      setGenerating(false);
    }
  }, [bookId, validId]);
  const handleRegenerate = useCallback(async () => {
    if (!schedule) return;
    setGenerating(true);
    setError(null);
    try {
      const updated = await schedulesApi.regenerateRecommendations(schedule.id);
      setSchedule(updated);
    } catch (err) {
      setError(err instanceof Error ? err.message : "Failed to regenerate recommendations.");
    } finally {
      setGenerating(false);
    }
  }, [schedule]);
  const handleConfirm = useCallback(async () => {
    if (!schedule) return;
    setError(null);
    try {
      const updated = await schedulesApi.confirmSchedule(schedule.id);
      setSchedule(updated);
    } catch (err) {
      setError(err instanceof Error ? err.message : "Failed to confirm schedule.");
    }
  }, [schedule]);
  /* ---- drag-and-drop handlers ---- */
  const handleDragStart = useCallback(
    (chapterId: number, sourceMeetingId: number | null) => (e: React.DragEvent) => {
      setDraggedChapter({ chapterId, sourceMeetingId });
      e.dataTransfer.effectAllowed = "move";
      e.dataTransfer.setData("text/plain", String(chapterId));
    },
    [],
  );
  const handleDragOver = useCallback(
    (targetMeetingId: number) => (e: React.DragEvent) => {
      e.preventDefault();
      e.dataTransfer.dropEffect = "move";
      setDropTarget(targetMeetingId);
    },
    [],
  );
  const handleDragLeave = useCallback(() => {
    setDropTarget(null);
  }, []);
  const handleDrop = useCallback(
    async (targetMeetingId: number) => {
      setDropTarget(null);
      if (!draggedChapter || !schedule) return;
      const { chapterId, sourceMeetingId } = draggedChapter;
      setDraggedChapter(null);
      // Same meeting — no-op
      if (sourceMeetingId === targetMeetingId) return;
      // Optimistically update UI
      const updatedMeetings = schedule.meetings.map((m) => ({
        ...m,
        chapter_ids: [...m.chapter_ids],
        chapters: [...m.chapters],
      }));
      // Remove from source
      if (sourceMeetingId !== null) {
        const source = updatedMeetings.find((m) => m.id === sourceMeetingId);
        if (source) {
          source.chapter_ids = source.chapter_ids.filter((id) => id !== chapterId);
          source.chapters = source.chapters.filter((ch) => ch.id !== chapterId);
        }
      }
      // Add to target
      const target = updatedMeetings.find((m) => m.id === targetMeetingId);
      if (target && !target.chapter_ids.includes(chapterId)) {
        target.chapter_ids = [...target.chapter_ids, chapterId];
        // Find chapter data
        const allChapters = schedule.meetings.flatMap((m) => m.chapters);
        const movedChapter = allChapters.find((ch) => ch.id === chapterId);
        if (movedChapter) {
          target.chapters = [...target.chapters, movedChapter];
        }
      }
      setSchedule({ ...schedule, meetings: updatedMeetings });
      // Persist to backend
      try {
        await schedulesApi.updateMeeting(schedule.id, targetMeetingId, {
          chapter_ids: target?.chapter_ids ?? [],
        });
        if (sourceMeetingId !== null) {
          const source = updatedMeetings.find((m) => m.id === sourceMeetingId);
          if (source) {
            await schedulesApi.updateMeeting(schedule.id, sourceMeetingId, {
              chapter_ids: source.chapter_ids,
            });
          }
        }
      } catch (err) {
        setError("Failed to save changes. Please try again.");
        // Reload to reset
        void loadData();
      }
    },
    [draggedChapter, schedule, loadData],
  );
  const handleUnassignDrop = useCallback(
    async () => {
      setDropTarget(null);
      if (!draggedChapter || !schedule) return;
      const { chapterId, sourceMeetingId } = draggedChapter;
      setDraggedChapter(null);
      if (sourceMeetingId === null) return;
      // Remove from source
      const updatedMeetings = schedule.meetings.map((m) => ({
        ...m,
        chapter_ids: [...m.chapter_ids],
        chapters: [...m.chapters],
      }));
      const source = updatedMeetings.find((m) => m.id === sourceMeetingId);
      if (source) {
        source.chapter_ids = source.chapter_ids.filter((id) => id !== chapterId);
        source.chapters = source.chapters.filter((ch) => ch.id !== chapterId);
      }
      setSchedule({ ...schedule, meetings: updatedMeetings });
      try {
        await schedulesApi.updateMeeting(schedule.id, sourceMeetingId, {
          chapter_ids: source?.chapter_ids ?? [],
        });
      } catch {
        setError("Failed to save changes.");
        void loadData();
      }
    },
    [draggedChapter, schedule, loadData],
  );
  const handleDragEnd = useCallback(() => {
    setDraggedChapter(null);
    setDropTarget(null);
  }, []);
  /* ---- styles ---- */
  const containerStyle: React.CSSProperties = {
    maxWidth: 1200,
    margin: "0 auto",
    padding: isMobile ? 12 : 24,
    minHeight: "100vh",
    background: "#f8f9fa",
  };
  const headerStyle: React.CSSProperties = {
    display: "flex",
    alignItems: "center",
    gap: 12,
    marginBottom: 24,
    flexWrap: "wrap",
  };
  const backBtnStyle: React.CSSProperties = {
    padding: "8px 16px",
    borderRadius: 8,
    border: "1px solid #e5e7eb",
    background: "#fff",
    color: "#374151",
    fontSize: 14,
    cursor: "pointer",
  };
  const btnPrimaryStyle: React.CSSProperties = {
    padding: "10px 24px",
    borderRadius: 8,
    border: "none",
    background: "#4f46e5",
    color: "#fff",
    fontSize: 14,
    fontWeight: 600,
    cursor: "pointer",
    opacity: generating ? 0.7 : 1,
    minHeight: 44,
  };
  const confirmBtnStyle: React.CSSProperties = {
    ...btnPrimaryStyle,
    background: "#16a34a",
  };
  const meetingsGridStyle: React.CSSProperties = {
    display: "grid",
    gridTemplateColumns: isMobile
      ? "1fr"
      : `repeat(${schedule?.meeting_count ?? 4}, 1fr)`,
    gap: 16,
    marginTop: 16,
  };
  const meetingCardStyle = (isDropTarget: boolean): React.CSSProperties => ({
    background: isDropTarget ? "#eef2ff" : "#fff",
    borderRadius: 12,
    border: `2px solid ${isDropTarget ? "#4f46e5" : "#e5e7eb"}`,
    padding: 16,
    minHeight: 200,
    transition: "border-color 0.2s, background 0.2s",
  });
  const chapterChipStyle: React.CSSProperties = {
    background: "#f3f4f6",
    borderRadius: 8,
    padding: "8px 12px",
    marginBottom: 8,
    cursor: "grab",
    fontSize: 13,
    color: "#374151",
    border: "1px solid #e5e7eb",
    userSelect: "none" as const,
  };
  /* ---- render ---- */
  if (!validId) {
    return (
      <div style={containerStyle}>
        <p style={{ color: "#ef4444" }}>Invalid ebook ID.</p>
      </div>
    );
  }
  if (loading) {
    return (
      <div style={containerStyle}>
        <div style={{ display: "flex", justifyContent: "center", alignItems: "center", minHeight: 400 }}>
          <p style={{ color: "#888" }}>{t("common.loading")}</p>
        </div>
      </div>
    );
  }
  if (error) {
    return (
      <div style={containerStyle}>
        <button onClick={() => navigate(-1)} style={backBtnStyle}>← Back</button>
        <div style={{ textAlign: "center", padding: 60 }}>
          <p style={{ color: "#ef4444", marginBottom: 16 }}>{error}</p>
          <button onClick={() => void loadData()} style={btnPrimaryStyle}>
            {t("common.retry")}
          </button>
        </div>
      </div>
    );
  }
  return (
    <div style={containerStyle}>
      {/* Header */}
      <div style={headerStyle}>
        <button onClick={() => navigate("/")} style={backBtnStyle}>
          ← {isMobile ? "Library" : "Back to Library"}
        </button>
        <div style={{ flex: 1 }}>
          <h1 style={{ fontSize: isMobile ? 18 : 24, margin: 0, color: "#1f2937" }}>
            Reading Schedule
          </h1>
          {ebook && (
            <p style={{ color: "#6b7280", fontSize: 14, margin: "4px 0 0" }}>
              {ebook.title}{ebook.author ? ` — ${ebook.author}` : ""}
            </p>
          )}
        </div>
        {!schedule && (
          <button onClick={handleGenerate} style={btnPrimaryStyle} disabled={generating}>
            {generating ? "Generating..." : "Generate Recommendations"}
          </button>
        )}
        {schedule && (
          <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
            <button onClick={handleRegenerate} style={btnPrimaryStyle} disabled={generating}>
              {generating ? "Regenerating..." : "Regenerate"}
            </button>
            {!schedule.confirmed && (
              <button onClick={handleConfirm} style={confirmBtnStyle}>
                Confirm Schedule
              </button>
            )}
          </div>
        )}
      </div>
      {/* Status badge */}
      {schedule && (
        <div style={{ marginBottom: 16 }}>
          <span style={{
            padding: "4px 12px",
            borderRadius: 999,
            fontSize: 13,
            fontWeight: 600,
            background: schedule.confirmed ? "#dcfce7" : "#fef3c7",
            color: schedule.confirmed ? "#16a34a" : "#b45309",
          }}>
            {schedule.confirmed ? "✓ Confirmed" : "Draft — drag chapters to adjust"}
          </span>
        </div>
      )}
      {/* No schedule yet */}
      {!schedule && (
        <div style={{ textAlign: "center", padding: "60px 16px" }}>
          <div style={{ fontSize: 48, marginBottom: 16 }}>📅</div>
          <h2 style={{ fontSize: 20, color: "#1f2937", marginBottom: 8 }}>
            No Schedule Yet
          </h2>
          <p style={{ color: "#6b7280", marginBottom: 24, maxWidth: 400, margin: "0 auto 24px" }}>
            Generate a reading schedule to split this book into balanced weekly assignments for your group.
          </p>
          <button onClick={handleGenerate} style={btnPrimaryStyle} disabled={generating}>
            {generating ? "Generating..." : "Generate Recommendations"}
          </button>
        </div>
      )}
      {/* Schedule meetings */}
      {schedule && (
        <>
          {/* Unassigned drop zone */}
          <div
            style={{
              padding: "12px 16px",
              background: dropTarget === null && draggedChapter ? "#fef2f2" : "#f9fafb",
              borderRadius: 8,
              border: `2px dashed ${dropTarget === null && draggedChapter ? "#ef4444" : "#d1d5db"}`,
              marginBottom: 16,
              textAlign: "center",
              color: "#6b7280",
              fontSize: 13,
              minHeight: 44,
              display: "flex",
              alignItems: "center",
              justifyContent: "center",
              transition: "all 0.2s",
            }}
            onDragOver={(e) => { e.preventDefault(); e.dataTransfer.dropEffect = "move"; setDropTarget(null); }}
            onDrop={handleUnassignDrop}
            onDragLeave={() => setDropTarget(null)}
          >
            {dropTarget === null && draggedChapter
              ? "Drop here to unassign"
              : "Drag chapters here to unassign from meetings"}
          </div>
          {/* Meetings grid */}
          <div style={meetingsGridStyle}>
            {schedule.meetings.map((meeting, idx) => (
              <MeetingColumn
                key={meeting.id}
                meeting={meeting}
                index={idx}
                isDropTarget={dropTarget === meeting.id}
                isConfirmed={schedule.confirmed}
                onDragStart={handleDragStart}
                onDragOver={handleDragOver(meeting.id)}
                onDragLeave={handleDragLeave}
                onDrop={() => void handleDrop(meeting.id)}
                onDragEnd={handleDragEnd}
              />
            ))}
          </div>
        </>
      )}
      {/* Drag overlay instruction */}
      {draggedChapter && (
        <div style={{
          position: "fixed",
          bottom: 24,
          left: "50%",
          transform: "translateX(-50%)",
          background: "#1f2937",
          color: "#fff",
          padding: "12px 24px",
          borderRadius: 12,
          fontSize: 14,
          boxShadow: "0 4px 16px rgba(0,0,0,0.2)",
          zIndex: 999,
        }}>
          Drop the chapter into a meeting column
        </div>
      )}
    </div>
  );
 }
 /* ---- Meeting Column Sub-component ---- */
 interface MeetingColumnProps {
  meeting: MeetingSection;
  index: number;
  isDropTarget: boolean;
  isConfirmed: boolean;
  onDragStart: (chapterId: number, sourceMeetingId: number | null) => (e: React.DragEvent) => void;
  onDragOver: (e: React.DragEvent) => void;
  onDragLeave: () => void;
  onDrop: () => void;
  onDragEnd: () => void;
 }
 function MeetingColumn({
  meeting,
  index,
  isDropTarget,
  isConfirmed,
  onDragStart,
  onDragOver,
  onDragLeave,
  onDrop,
  onDragEnd,
 }: MeetingColumnProps) {
  const chapterCount = meeting.chapter_ids.length;
  const cardStyle: React.CSSProperties = {
    background: isDropTarget ? "#eef2ff" : "#fff",
    borderRadius: 12,
    border: `2px solid ${isDropTarget ? "#4f46e5" : "#e5e7eb"}`,
    overflow: "hidden",
    transition: "border-color 0.2s, background 0.2s",
  };
  const headerStyle: React.CSSProperties = {
    padding: "12px 16px",
    background: "#f9fafb",
    borderBottom: "1px solid #e5e7eb",
  };
  const bodyStyle: React.CSSProperties = {
    padding: "12px 16px",
    minHeight: 120,
  };
  return (
    <div style={cardStyle}>
      <div style={headerStyle}>
        <div style={{ fontWeight: 700, color: "#1f2937", fontSize: 15, marginBottom: 4 }}>
          Week {index + 1}
        </div>
        <div style={{ display: "flex", gap: 16, fontSize: 12, color: "#6b7280" }}>
          <span>{chapterCount} {chapterCount === 1 ? "chapter" : "chapters"}</span>
          <span>{formatTime(meeting.estimated_time_minutes)}</span>
        </div>
      </div>
      <div
        style={bodyStyle}
        onDragOver={isConfirmed ? undefined : onDragOver}
        onDragLeave={isConfirmed ? undefined : onDragLeave}
        onDrop={isConfirmed ? undefined : onDrop}
      >
        {meeting.chapters.length === 0 && (
          <div style={{
            color: "#9ca3af",
            fontSize: 13,
            textAlign: "center",
            padding: "20px 0",
            fontStyle: "italic",
          }}>
            {isDropTarget ? "Drop here" : "No chapters assigned"}
          </div>
        )}
        {meeting.chapters.map((chapter) => (
          <div
            key={`${meeting.id}-${chapter.id}`}
            draggable={!isConfirmed}
            onDragStart={isConfirmed ? undefined : onDragStart(chapter.id, meeting.id)}
            onDragEnd={isConfirmed ? undefined : onDragEnd}
            style={{
              background: "#f3f4f6",
              borderRadius: 8,
              padding: "8px 12px",
              marginBottom: 8,
              cursor: isConfirmed ? "default" : "grab",
              fontSize: 13,
              color: "#374151",
              border: "1px solid #e5e7eb",
              userSelect: "none" as const,
              opacity: isConfirmed ? 0.8 : 1,
            }}
          >
            <div style={{ fontWeight: 600, marginBottom: 2 }}>{chapter.title}</div>
            {chapter.href && (
              <div style={{ fontSize: 11, color: "#9ca3af" }}>{chapter.href}</div>
            )}
          </div>
        ))}
      </div>
    </div>
  );
 }
@@ -2,7 +2,9 @@ import { useEffect, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18n-lite";
 import { booksApi } from "../api/books";
 import { groupsApi } from "../api/groups";
 import type { ReadingSettings } from "../types/book";
 import type { NotificationPreferences } from "../types/notifications";
 import type { SupportedLanguage } from "../locales";
 import { SimpleFormPageLayout } from "../components/layout/SimpleFormPageLayout";
@@ -17,6 +19,7 @@ export function SettingsPage() {
  const { t, language, setLanguage } = useTranslation();
  const navigate = useNavigate();
  const [settings, setSettings] = useState<ReadingSettings | null>(null);
  const [notifPrefs, setNotifPrefs] = useState<NotificationPreferences | null>(null);
  const [loading, setLoading] = useState(true);
  const [saving, setSaving] = useState(false);
  const [error, setError] = useState<string | null>(null);
@@ -24,7 +27,14 @@ export function SettingsPage() {
  useEffect(() => {
    const load = async () => {
-      try { const data = await booksApi.getSettings(); setSettings(data); }
+      try {
        const [data, notifData] = await Promise.all([
          booksApi.getSettings(),
          groupsApi.getPreferences(),
        ]);
        setSettings(data);
        setNotifPrefs(notifData);
      }
      catch (err) { setError(err instanceof Error ? err.message : t("settings.loadFailed")); }
      finally { setLoading(false); }
    };
@@ -32,9 +42,15 @@ export function SettingsPage() {
  }, [t]);
  const handleSave = async () => {
-    if (!settings) return;
+    if (!settings || !notifPrefs) return;
    setSaving(true); setError(null); setSuccess(false);
-    try { await booksApi.updateSettings(settings); setSuccess(true); setTimeout(() => setSuccess(false), 2000); }
+    try {
      await Promise.all([
        booksApi.updateSettings(settings),
        groupsApi.updatePreferences(notifPrefs),
      ]);
      setSuccess(true); setTimeout(() => setSuccess(false), 2000);
    }
    catch (err) { setError(err instanceof Error ? err.message : t("settings.saveFailed")); }
    finally { setSaving(false); }
  };
@@ -85,6 +101,48 @@ export function SettingsPage() {
          </div>
        </>}
        {notifPrefs && <>
          <div style={{ borderTop: "1px solid #e5e7eb", paddingTop: 20 }}>
            <h3 style={{ fontSize: 16, fontWeight: 600, color: "#1f2937", marginBottom: 16 }}>
              Notification Settings
            </h3>
            <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
              <label style={{ display: "flex", alignItems: "center", gap: 10, fontSize: 14, color: "#374151", cursor: "pointer" }}>
                <input
                  type="checkbox"
                  checked={notifPrefs.pace_notifications_enabled}
                  onChange={(e) => setNotifPrefs({ ...notifPrefs, pace_notifications_enabled: e.target.checked })}
                  style={{ width: 18, height: 18, cursor: "pointer" }}
                />
                Enable pace notifications
              </label>
              <label style={{ display: "flex", alignItems: "center", gap: 10, fontSize: 14, color: "#374151", cursor: "pointer" }}>
                <input
                  type="checkbox"
                  checked={notifPrefs.reminder_enabled}
                  onChange={(e) => setNotifPrefs({ ...notifPrefs, reminder_enabled: e.target.checked })}
                  style={{ width: 18, height: 18, cursor: "pointer" }}
                />
                Enable pre-meeting reminders (24h before)
              </label>
              <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
                <label style={{ fontSize: 14, fontWeight: 600, color: "#555" }}>Notification frequency</label>
                <select
                  value={notifPrefs.frequency}
                  onChange={(e) => setNotifPrefs({ ...notifPrefs, frequency: e.target.value as NotificationPreferences["frequency"] })}
                  style={{ padding: "10px 12px", borderRadius: 6, border: "1px solid #ddd", fontSize: 16, background: "#fff", outline: "none" }}
                >
                  <option value="daily">Daily</option>
                  <option value="weekly">Weekly</option>
                </select>
              </div>
            </div>
          </div>
        </>}
        <button onClick={handleSave} disabled={saving} style={{ padding: "12px 24px", borderRadius: 8, border: "none", background: "#1a1a2e", color: "#fff", fontSize: 16, fontWeight: 600, cursor: "pointer", opacity: saving ? 0.6 : 1, marginTop: 8 }}>{saving ? t("common.saving") : t("settings.saveSettings")}</button>
      </div>
    </SimpleFormPageLayout>
@@ -102,27 +102,3 @@ export interface BookSearchParams {
  page?: number;
  page_size?: number;
 }
 export interface MeetingSection {
  id: number;
  meeting_index: number;
  title: string;
  estimated_time_minutes: number;
  chapter_ids: number[];
  chapters: BookChapter[];
 }
 export interface ReadingSchedule {
  id: number;
  ebook: number;
  meeting_count: number;
  confirmed: boolean;
  meetings: MeetingSection[];
  created_at: string;
  updated_at: string;
 }
 export interface GenerateRecommendationsRequest {
  ebook_id: number;
  meeting_count?: number;
 }
@@ -0,0 +1,65 @@
 export interface PaceStatus {
  meeting_id: number;
  meeting_title: string;
  scheduled_at: string;
  target_section: number;
  target_section_label: string;
  current_section: number;
  ahead_behind_delta: number;
  status: "ahead" | "behind" | "on_track" | "completed";
  days_until_meeting: number;
  sections_to_catch_up: number;
  ebook_id: number;
  ebook_title: string;
 }
 export interface NotificationPreferences {
  pace_notifications_enabled: boolean;
  reminder_enabled: boolean;
  frequency: "daily" | "weekly";
 }
 export interface MeetingReminder {
  meeting_id: number;
  meeting_title: string;
  scheduled_at: string;
  target_section: number;
  target_section_label: string;
  group_name: string;
  hours_until: number;
  ebook_id: number;
  ebook_title: string;
 }
 export interface ReadingGroup {
  id: number;
  name: string;
  description: string;
  book: number | null;
  ebook: number | null;
  created_by: number;
  created_at: string;
  member_count: number;
  meeting_count: number;
 }
 export interface GroupMeeting {
  id: number;
  group: number;
  group_name: string;
  title: string;
  scheduled_at: string;
  target_section: number;
  target_section_label: string;
  created_at: string;
 }
 export interface GroupMembership {
  id: number;
  user: number;
  user_email: string;
  group: number;
  group_name: string;
  role: "admin" | "member";
  joined_at: string;
 }