Initial commit: Aurora Moments self-hosted photo/video sharing platform

Django/DRF + PostgreSQL/Redis/Celery backend with accounts, library,
moments, and notifications apps; React/TypeScript/Vite frontend with
Instagram-style sidebar nav, feed, profiles, nested comment replies,
notifications, and photo/video upload with ffmpeg-generated posters.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

api/.dockerignore

@@ -0,0 +1,7 @@
+__pycache__
+*.pyc
+.venv
+venv
+media
+staticfiles
+.env

api/Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libpq-dev gcc ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN mkdir -p /app/media /app/staticfiles
+
+EXPOSE 8000
+
+CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000"]

api/apps/accounts/admin.py

@@ -0,0 +1,18 @@
+from django.contrib import admin
+from django.contrib.auth.admin import UserAdmin as DjangoUserAdmin
+
+from .models import Follow, User
+
+
+@admin.register(User)
+class UserAdmin(DjangoUserAdmin):
+    fieldsets = DjangoUserAdmin.fieldsets + (
+        ("Aurora Moments profile", {"fields": ("display_name", "bio", "avatar", "is_private")}),
+    )
+    list_display = ("username", "email", "display_name", "is_private", "is_staff")
+
+
+@admin.register(Follow)
+class FollowAdmin(admin.ModelAdmin):
+    list_display = ("follower", "following", "status", "created_at")
+    list_filter = ("status",)

api/apps/accounts/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class AccountsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.accounts"
+    label = "accounts"

api/apps/accounts/migrations/0001_initial.py

@@ -0,0 +1,69 @@
+# Generated by Django 5.0.9 on 2026-08-09 17:00
+
+import django.contrib.auth.models
+import django.contrib.auth.validators
+import django.db.models.deletion
+import django.utils.timezone
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('auth', '0012_alter_user_first_name_max_length'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='User',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('password', models.CharField(max_length=128, verbose_name='password')),
+                ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')),
+                ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
+                ('username', models.CharField(error_messages={'unique': 'A user with that username already exists.'}, help_text='Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.', max_length=150, unique=True, validators=[django.contrib.auth.validators.UnicodeUsernameValidator()], verbose_name='username')),
+                ('first_name', models.CharField(blank=True, max_length=150, verbose_name='first name')),
+                ('last_name', models.CharField(blank=True, max_length=150, verbose_name='last name')),
+                ('is_staff', models.BooleanField(default=False, help_text='Designates whether the user can log into this admin site.', verbose_name='staff status')),
+                ('is_active', models.BooleanField(default=True, help_text='Designates whether this user should be treated as active. Unselect this instead of deleting accounts.', verbose_name='active')),
+                ('date_joined', models.DateTimeField(default=django.utils.timezone.now, verbose_name='date joined')),
+                ('email', models.EmailField(max_length=254, unique=True)),
+                ('display_name', models.CharField(blank=True, max_length=150)),
+                ('bio', models.TextField(blank=True, max_length=500)),
+                ('avatar', models.ImageField(blank=True, null=True, upload_to='avatars/')),
+                ('is_private', models.BooleanField(default=False, help_text='If true, new followers must be approved before they can see followers-only Moments.')),
+                ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.group', verbose_name='groups')),
+                ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.permission', verbose_name='user permissions')),
+            ],
+            options={
+                'verbose_name': 'user',
+                'verbose_name_plural': 'users',
+                'abstract': False,
+            },
+            managers=[
+                ('objects', django.contrib.auth.models.UserManager()),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Follow',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('status', models.CharField(choices=[('pending', 'Pending'), ('accepted', 'Accepted')], default='accepted', max_length=10)),
+                ('follower', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='following_edges', to=settings.AUTH_USER_MODEL)),
+                ('following', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='follower_edges', to=settings.AUTH_USER_MODEL)),
+            ],
+        ),
+        migrations.AddConstraint(
+            model_name='follow',
+            constraint=models.CheckConstraint(check=models.Q(('follower', models.F('following')), _negated=True), name='follow_no_self_follow'),
+        ),
+        migrations.AlterUniqueTogether(
+            name='follow',
+            unique_together={('follower', 'following')},
+        ),
+    ]

api/apps/accounts/models.py

@@ -0,0 +1,46 @@
+from django.contrib.auth.models import AbstractUser
+from django.db import models
+
+from apps.core.models import TimeStampedModel
+
+
+class User(AbstractUser):
+    """Aurora Moments account. Email is the login identifier; username is the
+    public @handle shown on profiles."""
+
+    email = models.EmailField(unique=True)
+    display_name = models.CharField(max_length=150, blank=True)
+    bio = models.TextField(max_length=500, blank=True)
+    avatar = models.ImageField(upload_to="avatars/", blank=True, null=True)
+    is_private = models.BooleanField(
+        default=False,
+        help_text="If true, new followers must be approved before they can see followers-only Moments.",
+    )
+
+    USERNAME_FIELD = "email"
+    REQUIRED_FIELDS = ["username"]
+
+    def __str__(self):
+        return self.username
+
+
+class Follow(TimeStampedModel):
+    class Status(models.TextChoices):
+        PENDING = "pending", "Pending"
+        ACCEPTED = "accepted", "Accepted"
+
+    follower = models.ForeignKey(User, related_name="following_edges", on_delete=models.CASCADE)
+    following = models.ForeignKey(User, related_name="follower_edges", on_delete=models.CASCADE)
+    status = models.CharField(max_length=10, choices=Status.choices, default=Status.ACCEPTED)
+
+    class Meta:
+        unique_together = ("follower", "following")
+        constraints = [
+            models.CheckConstraint(
+                check=~models.Q(follower=models.F("following")),
+                name="follow_no_self_follow",
+            )
+        ]
+
+    def __str__(self):
+        return f"{self.follower} -> {self.following} ({self.status})"

api/apps/accounts/serializers.py

@@ -0,0 +1,91 @@
+from django.contrib.auth import password_validation
+from rest_framework import serializers
+
+from .models import Follow, User
+
+
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ["id", "username", "display_name", "bio", "avatar", "is_private", "date_joined"]
+        read_only_fields = ["id", "date_joined"]
+
+
+class ProfileSerializer(UserSerializer):
+    """UserSerializer plus the counts/relationship state a profile page
+    needs. Kept separate from UserSerializer (used for owner/author fields
+    all over the feed) so those hot paths don't pay for two extra COUNT
+    queries per embedded user."""
+
+    follower_count = serializers.SerializerMethodField()
+    following_count = serializers.SerializerMethodField()
+    viewer_follow_id = serializers.SerializerMethodField()
+    viewer_follow_status = serializers.SerializerMethodField()
+
+    class Meta(UserSerializer.Meta):
+        fields = UserSerializer.Meta.fields + [
+            "follower_count", "following_count", "viewer_follow_id", "viewer_follow_status",
+        ]
+
+    def _viewer_follow(self, obj):
+        request = self.context.get("request")
+        if not request or not request.user.is_authenticated or request.user.id == obj.id:
+            return None
+        if not hasattr(obj, "_viewer_follow_cache"):
+            obj._viewer_follow_cache = Follow.objects.filter(follower=request.user, following=obj).first()
+        return obj._viewer_follow_cache
+
+    def get_follower_count(self, obj):
+        return obj.follower_edges.filter(status=Follow.Status.ACCEPTED).count()
+
+    def get_following_count(self, obj):
+        return obj.following_edges.filter(status=Follow.Status.ACCEPTED).count()
+
+    def get_viewer_follow_id(self, obj):
+        follow = self._viewer_follow(obj)
+        return follow.id if follow else None
+
+    def get_viewer_follow_status(self, obj):
+        follow = self._viewer_follow(obj)
+        return follow.status if follow else None
+
+
+class RegisterSerializer(serializers.ModelSerializer):
+    password = serializers.CharField(write_only=True)
+
+    class Meta:
+        model = User
+        fields = ["id", "email", "username", "password", "display_name"]
+
+    def validate_password(self, value):
+        password_validation.validate_password(value)
+        return value
+
+    def create(self, validated_data):
+        password = validated_data.pop("password")
+        user = User(**validated_data)
+        user.set_password(password)
+        user.save()
+        return user
+
+
+class FollowSerializer(serializers.ModelSerializer):
+    follower = UserSerializer(read_only=True)
+    following = UserSerializer(read_only=True)
+    following_id = serializers.PrimaryKeyRelatedField(
+        queryset=User.objects.all(), source="following", write_only=True
+    )
+
+    class Meta:
+        model = Follow
+        fields = ["id", "follower", "following", "following_id", "status", "created_at"]
+        read_only_fields = ["id", "follower", "status", "created_at"]
+
+    def create(self, validated_data):
+        follower = self.context["request"].user
+        following = validated_data["following"]
+        status = Follow.Status.PENDING if following.is_private else Follow.Status.ACCEPTED
+        follow, _ = Follow.objects.get_or_create(
+            follower=follower, following=following, defaults={"status": status}
+        )
+        return follow

api/apps/accounts/urls.py

@@ -0,0 +1,13 @@
+from django.urls import path
+from rest_framework.routers import DefaultRouter
+
+from .views import FollowViewSet, MeView, RegisterView, UserViewSet
+
+router = DefaultRouter()
+router.register("users", UserViewSet, basename="user")
+router.register("follows", FollowViewSet, basename="follow")
+
+urlpatterns = [
+    path("register/", RegisterView.as_view(), name="register"),
+    path("me/", MeView.as_view(), name="me"),
+] + router.urls

api/apps/accounts/views.py

@@ -0,0 +1,48 @@
+from rest_framework import generics, permissions, viewsets
+from rest_framework.exceptions import PermissionDenied
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from .models import Follow, User
+from .serializers import FollowSerializer, ProfileSerializer, RegisterSerializer, UserSerializer
+
+
+class RegisterView(generics.CreateAPIView):
+    queryset = User.objects.all()
+    serializer_class = RegisterSerializer
+    permission_classes = [permissions.AllowAny]
+
+
+class MeView(APIView):
+    def get(self, request):
+        return Response(ProfileSerializer(request.user, context={"request": request}).data)
+
+    def patch(self, request):
+        serializer = UserSerializer(request.user, data=request.data, partial=True, context={"request": request})
+        serializer.is_valid(raise_exception=True)
+        serializer.save()
+        return Response(serializer.data)
+
+
+class UserViewSet(viewsets.ReadOnlyModelViewSet):
+    queryset = User.objects.all()
+    serializer_class = ProfileSerializer
+    lookup_field = "username"
+
+
+class FollowViewSet(viewsets.ModelViewSet):
+    serializer_class = FollowSerializer
+    http_method_names = ["get", "post", "delete", "head", "options"]
+
+    def get_queryset(self):
+        user = self.request.user
+        qs = Follow.objects.select_related("follower", "following")
+        direction = self.request.query_params.get("direction", "following")
+        if direction == "followers":
+            return qs.filter(following=user)
+        return qs.filter(follower=user)
+
+    def perform_destroy(self, instance):
+        if instance.follower_id != self.request.user.id:
+            raise PermissionDenied("Cannot delete another user's follow edge.")
+        instance.delete()

api/apps/core/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class CoreConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.core"
+    label = "core"

api/apps/core/models.py

@@ -0,0 +1,29 @@
+import uuid
+
+from django.db import models
+
+
+class TimeStampedModel(models.Model):
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+
+
+class UUIDModel(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    class Meta:
+        abstract = True
+
+
+class Audience(models.TextChoices):
+    """Who can see a Moment or Album. Mirrors the concept doc's privacy model."""
+
+    PUBLIC = "public", "Public"
+    FOLLOWERS = "followers", "Followers"
+    FRIENDS = "friends", "Friends"
+    FAMILY = "family", "Family"
+    CUSTOM = "custom", "Custom"
+    ONLY_ME = "only_me", "Only Me"

api/apps/library/admin.py

@@ -0,0 +1,32 @@
+from django.contrib import admin
+
+from .models import Album, AlbumCollaborator, AlbumItem, LibraryItem, MediaRendition
+
+
+class MediaRenditionInline(admin.TabularInline):
+    model = MediaRendition
+    extra = 0
+
+
+@admin.register(LibraryItem)
+class LibraryItemAdmin(admin.ModelAdmin):
+    list_display = ("original_filename", "owner", "media_type", "processing_status", "captured_at")
+    list_filter = ("media_type", "processing_status")
+    search_fields = ("original_filename", "owner__username")
+    inlines = [MediaRenditionInline]
+
+
+class AlbumItemInline(admin.TabularInline):
+    model = AlbumItem
+    extra = 0
+
+
+class AlbumCollaboratorInline(admin.TabularInline):
+    model = AlbumCollaborator
+    extra = 0
+
+
+@admin.register(Album)
+class AlbumAdmin(admin.ModelAdmin):
+    list_display = ("name", "owner", "audience", "created_at")
+    inlines = [AlbumItemInline, AlbumCollaboratorInline]

api/apps/library/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class LibraryConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.library"
+    label = "library"

api/apps/library/migrations/0001_initial.py

@@ -0,0 +1,104 @@
+# Generated by Django 5.0.9 on 2026-08-09 17:00
+
+import apps.library.models
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='LibraryItem',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('file', models.FileField(upload_to=apps.library.models.library_upload_path)),
+                ('media_type', models.CharField(choices=[('photo', 'Photo'), ('video', 'Video')], max_length=10)),
+                ('original_filename', models.CharField(max_length=255)),
+                ('file_size', models.PositiveBigIntegerField(default=0)),
+                ('width', models.PositiveIntegerField(blank=True, null=True)),
+                ('height', models.PositiveIntegerField(blank=True, null=True)),
+                ('duration_seconds', models.FloatField(blank=True, null=True)),
+                ('captured_at', models.DateTimeField(blank=True, null=True)),
+                ('latitude', models.DecimalField(blank=True, decimal_places=6, max_digits=9, null=True)),
+                ('longitude', models.DecimalField(blank=True, decimal_places=6, max_digits=9, null=True)),
+                ('camera_make', models.CharField(blank=True, max_length=100)),
+                ('camera_model', models.CharField(blank=True, max_length=100)),
+                ('checksum', models.CharField(db_index=True, help_text='sha256 of the original file, used for dedup', max_length=64)),
+                ('processing_status', models.CharField(choices=[('pending', 'Pending'), ('processing', 'Processing'), ('ready', 'Ready'), ('failed', 'Failed')], default='pending', max_length=12)),
+                ('owner', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='library_items', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['-captured_at', '-created_at'],
+                'unique_together': {('owner', 'checksum')},
+            },
+        ),
+        migrations.CreateModel(
+            name='Album',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('name', models.CharField(max_length=150)),
+                ('description', models.TextField(blank=True)),
+                ('audience', models.CharField(choices=[('public', 'Public'), ('followers', 'Followers'), ('friends', 'Friends'), ('family', 'Family'), ('custom', 'Custom'), ('only_me', 'Only Me')], default='only_me', max_length=10)),
+                ('owner', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='albums', to=settings.AUTH_USER_MODEL)),
+                ('cover_item', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='+', to='library.libraryitem')),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='AlbumCollaborator',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('role', models.CharField(choices=[('viewer', 'Viewer'), ('contributor', 'Contributor'), ('admin', 'Admin')], default='viewer', max_length=11)),
+                ('status', models.CharField(choices=[('pending', 'Pending'), ('accepted', 'Accepted')], default='pending', max_length=8)),
+                ('album', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='collaborators', to='library.album')),
+                ('invited_by', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='+', to=settings.AUTH_USER_MODEL)),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='album_invites', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'unique_together': {('album', 'user')},
+            },
+        ),
+        migrations.CreateModel(
+            name='AlbumItem',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('added_at', models.DateTimeField(auto_now_add=True)),
+                ('added_by', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='+', to=settings.AUTH_USER_MODEL)),
+                ('album', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='items', to='library.album')),
+                ('library_item', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='album_items', to='library.libraryitem')),
+            ],
+            options={
+                'ordering': ['-added_at'],
+                'unique_together': {('album', 'library_item')},
+            },
+        ),
+        migrations.CreateModel(
+            name='MediaRendition',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('kind', models.CharField(choices=[('thumbnail', 'Thumbnail'), ('feed', 'Feed'), ('large', 'Large / Fullscreen')], max_length=10)),
+                ('file', models.FileField(upload_to=apps.library.models.rendition_upload_path)),
+                ('width', models.PositiveIntegerField()),
+                ('height', models.PositiveIntegerField()),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('library_item', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='renditions', to='library.libraryitem')),
+            ],
+            options={
+                'unique_together': {('library_item', 'kind')},
+            },
+        ),
+    ]

api/apps/library/models.py

@@ -0,0 +1,123 @@
+from django.conf import settings
+from django.db import models
+
+from apps.core.models import Audience, TimeStampedModel
+
+
+def library_upload_path(instance, filename):
+    return f"library/{instance.owner_id}/originals/{filename}"
+
+
+def rendition_upload_path(instance, filename):
+    return f"library/{instance.library_item.owner_id}/renditions/{instance.kind}/{filename}"
+
+
+class LibraryItem(TimeStampedModel):
+    """A single photo or video backed up to a user's private library.
+    Nothing here is visible to anyone but the owner until it is attached to
+    a Moment or a shared Album."""
+
+    class MediaType(models.TextChoices):
+        PHOTO = "photo", "Photo"
+        VIDEO = "video", "Video"
+
+    class ProcessingStatus(models.TextChoices):
+        PENDING = "pending", "Pending"
+        PROCESSING = "processing", "Processing"
+        READY = "ready", "Ready"
+        FAILED = "failed", "Failed"
+
+    owner = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="library_items", on_delete=models.CASCADE)
+    file = models.FileField(upload_to=library_upload_path)
+    media_type = models.CharField(max_length=10, choices=MediaType.choices)
+    original_filename = models.CharField(max_length=255)
+    file_size = models.PositiveBigIntegerField(default=0)
+    width = models.PositiveIntegerField(null=True, blank=True)
+    height = models.PositiveIntegerField(null=True, blank=True)
+    duration_seconds = models.FloatField(null=True, blank=True)
+
+    captured_at = models.DateTimeField(null=True, blank=True)
+    latitude = models.DecimalField(max_digits=9, decimal_places=6, null=True, blank=True)
+    longitude = models.DecimalField(max_digits=9, decimal_places=6, null=True, blank=True)
+    camera_make = models.CharField(max_length=100, blank=True)
+    camera_model = models.CharField(max_length=100, blank=True)
+
+    checksum = models.CharField(max_length=64, db_index=True, help_text="sha256 of the original file, used for dedup")
+    processing_status = models.CharField(
+        max_length=12, choices=ProcessingStatus.choices, default=ProcessingStatus.PENDING
+    )
+
+    class Meta:
+        unique_together = ("owner", "checksum")
+        ordering = ["-captured_at", "-created_at"]
+
+    def __str__(self):
+        return f"{self.original_filename} ({self.owner})"
+
+
+class MediaRendition(models.Model):
+    """A derived, smaller version of a LibraryItem (thumbnail/feed/large),
+    generated asynchronously so the original never has to be served to the
+    browser just to render a grid."""
+
+    class Kind(models.TextChoices):
+        THUMBNAIL = "thumbnail", "Thumbnail"
+        FEED = "feed", "Feed"
+        LARGE = "large", "Large / Fullscreen"
+
+    library_item = models.ForeignKey(LibraryItem, related_name="renditions", on_delete=models.CASCADE)
+    kind = models.CharField(max_length=10, choices=Kind.choices)
+    file = models.FileField(upload_to=rendition_upload_path)
+    width = models.PositiveIntegerField()
+    height = models.PositiveIntegerField()
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        unique_together = ("library_item", "kind")
+
+    def __str__(self):
+        return f"{self.library_item_id} - {self.kind}"
+
+
+class Album(TimeStampedModel):
+    owner = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="albums", on_delete=models.CASCADE)
+    name = models.CharField(max_length=150)
+    description = models.TextField(blank=True)
+    cover_item = models.ForeignKey(
+        LibraryItem, related_name="+", on_delete=models.SET_NULL, null=True, blank=True
+    )
+    audience = models.CharField(max_length=10, choices=Audience.choices, default=Audience.ONLY_ME)
+
+    def __str__(self):
+        return self.name
+
+
+class AlbumItem(models.Model):
+    album = models.ForeignKey(Album, related_name="items", on_delete=models.CASCADE)
+    library_item = models.ForeignKey(LibraryItem, related_name="album_items", on_delete=models.CASCADE)
+    added_by = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="+", on_delete=models.CASCADE)
+    added_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        unique_together = ("album", "library_item")
+        ordering = ["-added_at"]
+
+
+class AlbumCollaborator(models.Model):
+    class Role(models.TextChoices):
+        VIEWER = "viewer", "Viewer"
+        CONTRIBUTOR = "contributor", "Contributor"
+        ADMIN = "admin", "Admin"
+
+    class Status(models.TextChoices):
+        PENDING = "pending", "Pending"
+        ACCEPTED = "accepted", "Accepted"
+
+    album = models.ForeignKey(Album, related_name="collaborators", on_delete=models.CASCADE)
+    user = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="album_invites", on_delete=models.CASCADE)
+    role = models.CharField(max_length=11, choices=Role.choices, default=Role.VIEWER)
+    invited_by = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="+", on_delete=models.CASCADE)
+    status = models.CharField(max_length=8, choices=Status.choices, default=Status.PENDING)
+
+    class Meta:
+        unique_together = ("album", "user")

api/apps/library/permissions.py

@@ -0,0 +1,10 @@
+from rest_framework.permissions import BasePermission
+
+
+class IsOwner(BasePermission):
+    """Library items and albums are private by default — only the owner may
+    read or write them through these endpoints. Sharing happens explicitly
+    via Moments / AlbumCollaborators, handled by their own views."""
+
+    def has_object_permission(self, request, view, obj):
+        return obj.owner_id == request.user.id

api/apps/library/serializers.py

@@ -0,0 +1,83 @@
+import hashlib
+
+from rest_framework import serializers
+
+from apps.accounts.models import User
+from apps.accounts.serializers import UserSerializer
+
+from .models import Album, AlbumCollaborator, AlbumItem, LibraryItem, MediaRendition
+
+
+class MediaRenditionSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = MediaRendition
+        fields = ["kind", "file", "width", "height"]
+
+
+class LibraryItemSerializer(serializers.ModelSerializer):
+    renditions = MediaRenditionSerializer(many=True, read_only=True)
+
+    class Meta:
+        model = LibraryItem
+        fields = [
+            "id", "file", "media_type", "original_filename", "file_size",
+            "width", "height", "duration_seconds", "captured_at",
+            "latitude", "longitude", "camera_make", "camera_model",
+            "processing_status", "renditions", "created_at",
+        ]
+        read_only_fields = [
+            "id", "width", "height", "duration_seconds", "captured_at",
+            "camera_make", "camera_model", "processing_status", "renditions", "created_at",
+        ]
+
+    def create(self, validated_data):
+        upload = validated_data["file"]
+        checksum = hashlib.sha256(upload.read()).hexdigest()
+        upload.seek(0)
+        validated_data["checksum"] = checksum
+        validated_data["file_size"] = upload.size
+        validated_data.setdefault("original_filename", upload.name)
+        validated_data["owner"] = self.context["request"].user
+        library_item, _created = LibraryItem.objects.get_or_create(
+            owner=validated_data["owner"],
+            checksum=checksum,
+            defaults=validated_data,
+        )
+        return library_item
+
+
+class AlbumItemSerializer(serializers.ModelSerializer):
+    library_item = LibraryItemSerializer(read_only=True)
+    library_item_id = serializers.PrimaryKeyRelatedField(
+        queryset=LibraryItem.objects.all(), source="library_item", write_only=True
+    )
+
+    class Meta:
+        model = AlbumItem
+        fields = ["id", "album", "library_item", "library_item_id", "added_by", "added_at"]
+        read_only_fields = ["id", "album", "added_by", "added_at"]
+
+
+class AlbumCollaboratorSerializer(serializers.ModelSerializer):
+    user = UserSerializer(read_only=True)
+    user_id = serializers.PrimaryKeyRelatedField(
+        queryset=User.objects.all(), source="user", write_only=True
+    )
+
+    class Meta:
+        model = AlbumCollaborator
+        fields = ["id", "album", "user", "user_id", "role", "status", "invited_by"]
+        read_only_fields = ["id", "album", "status", "invited_by"]
+
+
+class AlbumSerializer(serializers.ModelSerializer):
+    items = AlbumItemSerializer(many=True, read_only=True)
+    collaborators = AlbumCollaboratorSerializer(many=True, read_only=True)
+
+    class Meta:
+        model = Album
+        fields = [
+            "id", "owner", "name", "description", "cover_item", "audience",
+            "items", "collaborators", "created_at", "updated_at",
+        ]
+        read_only_fields = ["id", "owner", "items", "collaborators", "created_at", "updated_at"]

api/apps/library/tasks.py

@@ -0,0 +1,159 @@
+import io
+import json
+import os
+import subprocess
+import tempfile
+from datetime import datetime
+
+from celery import shared_task
+from django.core.files.base import ContentFile
+from PIL import ExifTags, Image
+
+from .models import LibraryItem, MediaRendition
+
+RENDITION_MAX_DIMENSIONS = {
+    MediaRendition.Kind.THUMBNAIL: 300,
+    MediaRendition.Kind.FEED: 1080,
+    MediaRendition.Kind.LARGE: 2048,
+}
+
+
+@shared_task
+def process_library_item(library_item_id):
+    try:
+        item = LibraryItem.objects.get(id=library_item_id)
+    except LibraryItem.DoesNotExist:
+        return
+
+    item.processing_status = LibraryItem.ProcessingStatus.PROCESSING
+    item.save(update_fields=["processing_status"])
+
+    try:
+        if item.media_type == LibraryItem.MediaType.PHOTO:
+            _process_photo(item)
+        else:
+            # Full transcoding to web-friendly renditions is a V1.5 feature
+            # (see README); the original file is served as-is for playback.
+            # We do extract dimensions/duration and a poster-frame thumbnail
+            # so videos aren't blank tiles in the UI.
+            _process_video(item)
+        item.processing_status = LibraryItem.ProcessingStatus.READY
+    except Exception:
+        item.processing_status = LibraryItem.ProcessingStatus.FAILED
+        raise
+    finally:
+        item.save(update_fields=["processing_status"])
+
+
+def _process_photo(item):
+    with item.file.open("rb") as fh:
+        image = Image.open(fh)
+        image.load()
+
+        for field, value in _extract_exif(image).items():
+            setattr(item, field, value)
+        item.width, item.height = image.size
+        item.save()
+
+        _write_renditions(item, image)
+
+
+def _process_video(item):
+    suffix = os.path.splitext(item.original_filename)[1] or ".mp4"
+    with tempfile.NamedTemporaryFile(suffix=suffix) as src:
+        with item.file.open("rb") as fh:
+            for chunk in fh.chunks():
+                src.write(chunk)
+        src.flush()
+
+        probe = _ffprobe(src.name)
+        if probe:
+            item.width = probe.get("width") or item.width
+            item.height = probe.get("height") or item.height
+            item.duration_seconds = probe.get("duration")
+            item.save()
+
+        # A missing/corrupt frame just means no poster image; the video
+        # itself still uploaded fine, so this must not fail the whole job.
+        try:
+            frame_bytes = _extract_poster_frame(src.name, probe.get("duration") if probe else None)
+            if frame_bytes:
+                image = Image.open(io.BytesIO(frame_bytes))
+                image.load()
+                _write_renditions(item, image)
+        except Exception:
+            pass
+
+
+def _write_renditions(item, image):
+    for kind, max_dimension in RENDITION_MAX_DIMENSIONS.items():
+        rendition_image = image.copy()
+        rendition_image.thumbnail((max_dimension, max_dimension))
+        rgb_image = rendition_image.convert("RGB")
+        buffer = io.BytesIO()
+        rgb_image.save(buffer, format="JPEG", quality=85)
+        MediaRendition.objects.update_or_create(
+            library_item=item,
+            kind=kind,
+            defaults={
+                "width": rendition_image.width,
+                "height": rendition_image.height,
+                "file": ContentFile(buffer.getvalue(), name=f"{item.id}_{kind}.jpg"),
+            },
+        )
+
+
+def _ffprobe(path):
+    try:
+        result = subprocess.run(
+            [
+                "ffprobe", "-v", "error", "-select_streams", "v:0",
+                "-show_entries", "stream=width,height:format=duration",
+                "-of", "json", path,
+            ],
+            capture_output=True, text=True, timeout=30, check=True,
+        )
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
+        return None
+    data = json.loads(result.stdout)
+    streams = data.get("streams") or [{}]
+    duration = (data.get("format") or {}).get("duration")
+    return {
+        "width": streams[0].get("width"),
+        "height": streams[0].get("height"),
+        "duration": float(duration) if duration else None,
+    }
+
+
+def _extract_poster_frame(path, duration_seconds):
+    timestamp = min(1.0, duration_seconds / 2) if duration_seconds else 0.1
+    with tempfile.NamedTemporaryFile(suffix=".jpg") as out:
+        try:
+            subprocess.run(
+                ["ffmpeg", "-y", "-ss", str(timestamp), "-i", path, "-frames:v", "1", "-q:v", "3", out.name],
+                capture_output=True, timeout=30, check=True,
+            )
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
+            return None
+        return out.read()
+
+
+def _extract_exif(image):
+    result = {}
+    raw_exif = image.getexif()
+    if not raw_exif:
+        return result
+    tags = {ExifTags.TAGS.get(tag_id, tag_id): value for tag_id, value in raw_exif.items()}
+
+    if tags.get("Make"):
+        result["camera_make"] = str(tags["Make"]).strip()
+    if tags.get("Model"):
+        result["camera_model"] = str(tags["Model"]).strip()
+
+    date_str = tags.get("DateTimeOriginal") or tags.get("DateTime")
+    if date_str:
+        try:
+            result["captured_at"] = datetime.strptime(str(date_str), "%Y:%m:%d %H:%M:%S")
+        except ValueError:
+            pass
+    return result

api/apps/library/urls.py

@@ -0,0 +1,20 @@
+from django.urls import path
+from rest_framework.routers import DefaultRouter
+
+from .views import AlbumCollaboratorViewSet, AlbumItemViewSet, AlbumViewSet, LibraryItemViewSet
+
+router = DefaultRouter()
+router.register("items", LibraryItemViewSet, basename="library-item")
+router.register("albums", AlbumViewSet, basename="album")
+
+album_items_list = AlbumItemViewSet.as_view({"get": "list", "post": "create"})
+album_items_detail = AlbumItemViewSet.as_view({"get": "retrieve", "delete": "destroy"})
+album_collaborators_list = AlbumCollaboratorViewSet.as_view({"get": "list", "post": "create"})
+album_collaborators_detail = AlbumCollaboratorViewSet.as_view({"get": "retrieve", "delete": "destroy"})
+
+urlpatterns = [
+    path("albums/<int:album_pk>/items/", album_items_list, name="album-items-list"),
+    path("albums/<int:album_pk>/items/<int:pk>/", album_items_detail, name="album-items-detail"),
+    path("albums/<int:album_pk>/collaborators/", album_collaborators_list, name="album-collaborators-list"),
+    path("albums/<int:album_pk>/collaborators/<int:pk>/", album_collaborators_detail, name="album-collaborators-detail"),
+] + router.urls

api/apps/library/views.py

@@ -0,0 +1,67 @@
+from rest_framework import permissions, viewsets
+from rest_framework.exceptions import PermissionDenied
+
+from .models import Album, AlbumCollaborator, AlbumItem, LibraryItem
+from .permissions import IsOwner
+from .serializers import AlbumCollaboratorSerializer, AlbumItemSerializer, AlbumSerializer, LibraryItemSerializer
+from .tasks import process_library_item
+
+
+class LibraryItemViewSet(viewsets.ModelViewSet):
+    serializer_class = LibraryItemSerializer
+    permission_classes = [permissions.IsAuthenticated, IsOwner]
+
+    def get_queryset(self):
+        return LibraryItem.objects.filter(owner=self.request.user)
+
+    def perform_create(self, serializer):
+        item = serializer.save()
+        process_library_item.delay(str(item.id))
+
+
+class AlbumViewSet(viewsets.ModelViewSet):
+    serializer_class = AlbumSerializer
+    permission_classes = [permissions.IsAuthenticated, IsOwner]
+
+    def get_queryset(self):
+        return Album.objects.filter(owner=self.request.user).prefetch_related("items", "collaborators")
+
+    def perform_create(self, serializer):
+        serializer.save(owner=self.request.user)
+
+
+class AlbumItemViewSet(viewsets.ModelViewSet):
+    serializer_class = AlbumItemSerializer
+    permission_classes = [permissions.IsAuthenticated]
+    http_method_names = ["get", "post", "delete", "head", "options"]
+
+    def _get_album(self):
+        album = Album.objects.get(pk=self.kwargs["album_pk"])
+        allowed = album.owner_id == self.request.user.id or album.collaborators.filter(
+            user=self.request.user, role=AlbumCollaborator.Role.CONTRIBUTOR, status=AlbumCollaborator.Status.ACCEPTED
+        ).exists()
+        if not allowed:
+            raise PermissionDenied("Not a contributor on this album.")
+        return album
+
+    def get_queryset(self):
+        return AlbumItem.objects.filter(album=self._get_album())
+
+    def perform_create(self, serializer):
+        serializer.save(album=self._get_album(), added_by=self.request.user)
+
+
+class AlbumCollaboratorViewSet(viewsets.ModelViewSet):
+    serializer_class = AlbumCollaboratorSerializer
+    permission_classes = [permissions.IsAuthenticated]
+    http_method_names = ["get", "post", "delete", "head", "options"]
+
+    def _get_album(self):
+        album = Album.objects.get(pk=self.kwargs["album_pk"], owner=self.request.user)
+        return album
+
+    def get_queryset(self):
+        return AlbumCollaborator.objects.filter(album=self._get_album())
+
+    def perform_create(self, serializer):
+        serializer.save(album=self._get_album(), invited_by=self.request.user)

api/apps/moments/admin.py

@@ -0,0 +1,19 @@
+from django.contrib import admin
+
+from .models import Comment, Moment, MomentItem, Reaction
+
+
+class MomentItemInline(admin.TabularInline):
+    model = MomentItem
+    extra = 0
+
+
+@admin.register(Moment)
+class MomentAdmin(admin.ModelAdmin):
+    list_display = ("id", "owner", "audience", "created_at")
+    list_filter = ("audience",)
+    inlines = [MomentItemInline]
+
+
+admin.site.register(Comment)
+admin.site.register(Reaction)

api/apps/moments/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class MomentsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.moments"
+    label = "moments"

api/apps/moments/migrations/0001_initial.py

@@ -0,0 +1,74 @@
+# Generated by Django 5.0.9 on 2026-08-09 17:00
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('library', '0001_initial'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Moment',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('caption', models.TextField(blank=True, max_length=2200)),
+                ('location', models.CharField(blank=True, max_length=255)),
+                ('audience', models.CharField(choices=[('public', 'Public'), ('followers', 'Followers'), ('friends', 'Friends'), ('family', 'Family'), ('custom', 'Custom'), ('only_me', 'Only Me')], default='public', max_length=10)),
+                ('owner', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='moments', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['-created_at'],
+            },
+        ),
+        migrations.CreateModel(
+            name='Comment',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('body', models.TextField(max_length=1000)),
+                ('author', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='comments', to=settings.AUTH_USER_MODEL)),
+                ('parent', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='replies', to='moments.comment')),
+                ('moment', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='comments', to='moments.moment')),
+            ],
+            options={
+                'ordering': ['created_at'],
+            },
+        ),
+        migrations.CreateModel(
+            name='MomentItem',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('order', models.PositiveIntegerField(default=0)),
+                ('library_item', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='moment_items', to='library.libraryitem')),
+                ('moment', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='items', to='moments.moment')),
+            ],
+            options={
+                'ordering': ['order'],
+                'unique_together': {('moment', 'library_item')},
+            },
+        ),
+        migrations.CreateModel(
+            name='Reaction',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('reaction_type', models.CharField(choices=[('like', 'Like')], default='like', max_length=10)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('moment', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='reactions', to='moments.moment')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='reactions', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'unique_together': {('moment', 'user')},
+            },
+        ),
+    ]

api/apps/moments/models.py

@@ -0,0 +1,85 @@
+from django.conf import settings
+from django.db import models
+
+from apps.core.models import Audience, TimeStampedModel
+from apps.library.models import LibraryItem
+
+
+class MomentQuerySet(models.QuerySet):
+    def visible_to(self, user):
+        """FAMILY and CUSTOM audiences intentionally fall back to
+        owner-only visibility until circles/custom-audience membership
+        (V1.5) exists — better to under-share than leak content."""
+        from apps.accounts.models import Follow
+
+        following_ids = Follow.objects.filter(
+            follower=user, status=Follow.Status.ACCEPTED
+        ).values_list("following_id", flat=True)
+        follower_ids = set(
+            Follow.objects.filter(
+                following=user, status=Follow.Status.ACCEPTED
+            ).values_list("follower_id", flat=True)
+        )
+        friend_ids = follower_ids & set(following_ids)
+
+        return self.filter(
+            models.Q(owner=user)
+            | models.Q(audience=Audience.PUBLIC)
+            | models.Q(audience=Audience.FOLLOWERS, owner_id__in=following_ids)
+            | models.Q(audience=Audience.FRIENDS, owner_id__in=friend_ids)
+        ).distinct()
+
+
+class Moment(TimeStampedModel):
+    """The social-media object: one or more LibraryItems shared with an
+    explicit audience. Sharing a Moment never moves or copies the original
+    file — it just makes the existing library item visible to others."""
+
+    owner = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="moments", on_delete=models.CASCADE)
+    caption = models.TextField(max_length=2200, blank=True)
+    location = models.CharField(max_length=255, blank=True)
+    audience = models.CharField(max_length=10, choices=Audience.choices, default=Audience.PUBLIC)
+
+    objects = MomentQuerySet.as_manager()
+
+    class Meta:
+        ordering = ["-created_at"]
+
+    def __str__(self):
+        return f"Moment({self.id}) by {self.owner}"
+
+
+class MomentItem(models.Model):
+    moment = models.ForeignKey(Moment, related_name="items", on_delete=models.CASCADE)
+    library_item = models.ForeignKey(LibraryItem, related_name="moment_items", on_delete=models.CASCADE)
+    order = models.PositiveIntegerField(default=0)
+
+    class Meta:
+        ordering = ["order"]
+        unique_together = ("moment", "library_item")
+
+
+class Comment(TimeStampedModel):
+    moment = models.ForeignKey(Moment, related_name="comments", on_delete=models.CASCADE)
+    author = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="comments", on_delete=models.CASCADE)
+    parent = models.ForeignKey("self", related_name="replies", on_delete=models.CASCADE, null=True, blank=True)
+    body = models.TextField(max_length=1000)
+
+    class Meta:
+        ordering = ["created_at"]
+
+    def __str__(self):
+        return f"{self.author}: {self.body[:40]}"
+
+
+class Reaction(models.Model):
+    class ReactionType(models.TextChoices):
+        LIKE = "like", "Like"
+
+    moment = models.ForeignKey(Moment, related_name="reactions", on_delete=models.CASCADE)
+    user = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="reactions", on_delete=models.CASCADE)
+    reaction_type = models.CharField(max_length=10, choices=ReactionType.choices, default=ReactionType.LIKE)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        unique_together = ("moment", "user")

api/apps/moments/permissions.py

@@ -0,0 +1,8 @@
+from rest_framework.permissions import SAFE_METHODS, BasePermission
+
+
+class IsOwnerOrReadOnly(BasePermission):
+    def has_object_permission(self, request, view, obj):
+        if request.method in SAFE_METHODS:
+            return True
+        return obj.owner_id == request.user.id

api/apps/moments/serializers.py

@@ -0,0 +1,103 @@
+from django.db import transaction
+from rest_framework import serializers
+
+from apps.accounts.serializers import UserSerializer
+from apps.library.models import LibraryItem
+from apps.library.serializers import LibraryItemSerializer
+
+from .models import Comment, Moment, MomentItem, Reaction
+
+
+class MomentItemSerializer(serializers.ModelSerializer):
+    library_item = LibraryItemSerializer(read_only=True)
+
+    class Meta:
+        model = MomentItem
+        fields = ["id", "library_item", "order"]
+
+
+class CommentSerializer(serializers.ModelSerializer):
+    author = UserSerializer(read_only=True)
+
+    class Meta:
+        model = Comment
+        fields = ["id", "moment", "author", "parent", "body", "created_at"]
+        read_only_fields = ["id", "moment", "author", "created_at"]
+
+    def validate_parent(self, value):
+        if value is None:
+            return value
+        if value.parent_id is not None:
+            raise serializers.ValidationError("Cannot reply to a reply; reply to the original comment instead.")
+        moment = self.context.get("moment")
+        if moment is not None and value.moment_id != moment.id:
+            raise serializers.ValidationError("Reply must target a comment on the same Moment.")
+        return value
+
+
+class ReactionSerializer(serializers.ModelSerializer):
+    user = UserSerializer(read_only=True)
+
+    class Meta:
+        model = Reaction
+        fields = ["id", "moment", "user", "reaction_type", "created_at"]
+        read_only_fields = ["id", "moment", "user", "created_at"]
+
+
+class MomentSerializer(serializers.ModelSerializer):
+    owner = UserSerializer(read_only=True)
+    items = MomentItemSerializer(many=True, read_only=True)
+    library_item_ids = serializers.PrimaryKeyRelatedField(
+        queryset=LibraryItem.objects.all(), many=True, write_only=True, source="library_items", required=False
+    )
+    comment_count = serializers.IntegerField(source="comments.count", read_only=True)
+    reaction_count = serializers.IntegerField(source="reactions.count", read_only=True)
+    viewer_reaction_id = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Moment
+        fields = [
+            "id", "owner", "caption", "location", "audience", "items",
+            "library_item_ids", "comment_count", "reaction_count", "viewer_reaction_id",
+            "created_at", "updated_at",
+        ]
+        read_only_fields = [
+            "id", "owner", "items", "comment_count", "reaction_count", "viewer_reaction_id",
+            "created_at", "updated_at",
+        ]
+
+    def get_viewer_reaction_id(self, obj):
+        request = self.context.get("request")
+        if not request or not request.user.is_authenticated:
+            return None
+        # obj.reactions is prefetched by the view, so this doesn't re-query per moment.
+        reaction = next((r for r in obj.reactions.all() if r.user_id == request.user.id), None)
+        return reaction.id if reaction else None
+
+    def validate_library_item_ids(self, library_items):
+        request = self.context["request"]
+        seen_ids = set()
+        for item in library_items:
+            if item.owner_id != request.user.id:
+                raise serializers.ValidationError("Can only share items from your own library.")
+            if item.id in seen_ids:
+                raise serializers.ValidationError("The same photo was selected more than once.")
+            seen_ids.add(item.id)
+        return library_items
+
+    def validate(self, attrs):
+        library_items = attrs.get("library_items", [])
+        caption = attrs.get("caption", "")
+        if not library_items and not caption.strip():
+            raise serializers.ValidationError("A Moment needs a caption or at least one photo.")
+        return attrs
+
+    def create(self, validated_data):
+        library_items = validated_data.pop("library_items", [])
+        validated_data["owner"] = self.context["request"].user
+        with transaction.atomic():
+            moment = Moment.objects.create(**validated_data)
+            MomentItem.objects.bulk_create(
+                [MomentItem(moment=moment, library_item=item, order=i) for i, item in enumerate(library_items)]
+            )
+        return moment

api/apps/moments/urls.py

@@ -0,0 +1,19 @@
+from django.urls import path
+from rest_framework.routers import DefaultRouter
+
+from .views import CommentViewSet, MomentViewSet, ReactionViewSet
+
+router = DefaultRouter()
+router.register("", MomentViewSet, basename="moment")
+
+comments_list = CommentViewSet.as_view({"get": "list", "post": "create"})
+comments_detail = CommentViewSet.as_view({"get": "retrieve", "delete": "destroy"})
+reactions_list = ReactionViewSet.as_view({"get": "list", "post": "create"})
+reactions_detail = ReactionViewSet.as_view({"get": "retrieve", "delete": "destroy"})
+
+urlpatterns = [
+    path("<int:moment_pk>/comments/", comments_list, name="moment-comments-list"),
+    path("<int:moment_pk>/comments/<int:pk>/", comments_detail, name="moment-comments-detail"),
+    path("<int:moment_pk>/reactions/", reactions_list, name="moment-reactions-list"),
+    path("<int:moment_pk>/reactions/<int:pk>/", reactions_detail, name="moment-reactions-detail"),
+] + router.urls

api/apps/moments/views.py

@@ -0,0 +1,69 @@
+from rest_framework import permissions, viewsets
+from rest_framework.exceptions import PermissionDenied
+
+from .models import Comment, Moment, Reaction
+from .permissions import IsOwnerOrReadOnly
+from .serializers import CommentSerializer, MomentSerializer, ReactionSerializer
+
+
+class MomentViewSet(viewsets.ModelViewSet):
+    """list() is the home feed: everything visible to the requesting user,
+    newest first. Filter to one user's posts (for a profile page) with
+    ?owner__username=<username> — still scoped by visible_to() below, so a
+    private/followers-only post won't leak through the filter."""
+
+    serializer_class = MomentSerializer
+    permission_classes = [permissions.IsAuthenticated, IsOwnerOrReadOnly]
+    filterset_fields = ["owner__username"]
+
+    def get_queryset(self):
+        return (
+            Moment.objects.visible_to(self.request.user)
+            .select_related("owner")
+            .prefetch_related("items__library_item__renditions", "reactions")
+        )
+
+
+class CommentViewSet(viewsets.ModelViewSet):
+    serializer_class = CommentSerializer
+    permission_classes = [permissions.IsAuthenticated]
+    http_method_names = ["get", "post", "delete", "head", "options"]
+
+    def _get_moment(self):
+        return Moment.objects.visible_to(self.request.user).get(pk=self.kwargs["moment_pk"])
+
+    def get_queryset(self):
+        return Comment.objects.filter(moment=self._get_moment()).select_related("author")
+
+    def get_serializer_context(self):
+        context = super().get_serializer_context()
+        context["moment"] = self._get_moment()
+        return context
+
+    def perform_create(self, serializer):
+        serializer.save(moment=self._get_moment(), author=self.request.user)
+
+    def perform_destroy(self, instance):
+        if instance.author_id != self.request.user.id and instance.moment.owner_id != self.request.user.id:
+            raise PermissionDenied("Cannot delete another user's comment.")
+        instance.delete()
+
+
+class ReactionViewSet(viewsets.ModelViewSet):
+    serializer_class = ReactionSerializer
+    permission_classes = [permissions.IsAuthenticated]
+    http_method_names = ["get", "post", "delete", "head", "options"]
+
+    def _get_moment(self):
+        return Moment.objects.visible_to(self.request.user).get(pk=self.kwargs["moment_pk"])
+
+    def get_queryset(self):
+        return Reaction.objects.filter(moment=self._get_moment()).select_related("user")
+
+    def perform_create(self, serializer):
+        serializer.save(moment=self._get_moment(), user=self.request.user)
+
+    def perform_destroy(self, instance):
+        if instance.user_id != self.request.user.id:
+            raise PermissionDenied("Cannot remove another user's reaction.")
+        instance.delete()

api/apps/notifications/admin.py

@@ -0,0 +1,9 @@
+from django.contrib import admin
+
+from .models import Notification
+
+
+@admin.register(Notification)
+class NotificationAdmin(admin.ModelAdmin):
+    list_display = ["id", "recipient", "actor", "verb", "moment", "is_read", "created_at"]
+    list_filter = ["verb", "is_read"]

api/apps/notifications/apps.py

@@ -0,0 +1,10 @@
+from django.apps import AppConfig
+
+
+class NotificationsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.notifications"
+    label = "notifications"
+
+    def ready(self):
+        from . import signals  # noqa: F401

api/apps/notifications/migrations/0001_initial.py

@@ -0,0 +1,35 @@
+# Generated by Django 5.0.9 on 2026-08-09 21:28
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('moments', '0001_initial'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Notification',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('verb', models.CharField(choices=[('like', 'Like'), ('comment', 'Comment'), ('reply', 'Reply')], max_length=10)),
+                ('is_read', models.BooleanField(default=False)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('actor', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='+', to=settings.AUTH_USER_MODEL)),
+                ('comment', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='notifications', to='moments.comment')),
+                ('moment', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='notifications', to='moments.moment')),
+                ('recipient', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='notifications', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['-created_at'],
+                'indexes': [models.Index(fields=['recipient', 'is_read'], name='notificatio_recipie_4e3567_idx')],
+            },
+        ),
+    ]

api/apps/notifications/models.py

@@ -0,0 +1,31 @@
+from django.conf import settings
+from django.db import models
+
+
+class Notification(models.Model):
+    """Tells `recipient` that `actor` did something (`verb`) involving
+    `moment` (and, for comment/reply verbs, the specific `comment`).
+    Created by signal handlers in signals.py — never directly by API
+    consumers."""
+
+    class Verb(models.TextChoices):
+        LIKE = "like", "Like"
+        COMMENT = "comment", "Comment"
+        REPLY = "reply", "Reply"
+
+    recipient = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="notifications", on_delete=models.CASCADE)
+    actor = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="+", on_delete=models.CASCADE)
+    verb = models.CharField(max_length=10, choices=Verb.choices)
+    moment = models.ForeignKey("moments.Moment", related_name="notifications", on_delete=models.CASCADE)
+    comment = models.ForeignKey(
+        "moments.Comment", null=True, blank=True, related_name="notifications", on_delete=models.CASCADE
+    )
+    is_read = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        ordering = ["-created_at"]
+        indexes = [models.Index(fields=["recipient", "is_read"])]
+
+    def __str__(self):
+        return f"{self.actor} {self.verb} -> {self.recipient}"

api/apps/notifications/serializers.py

@@ -0,0 +1,16 @@
+from rest_framework import serializers
+
+from apps.accounts.serializers import UserSerializer
+
+from .models import Notification
+
+
+class NotificationSerializer(serializers.ModelSerializer):
+    actor = UserSerializer(read_only=True)
+    moment_id = serializers.IntegerField(read_only=True)
+    comment_id = serializers.IntegerField(read_only=True)
+
+    class Meta:
+        model = Notification
+        fields = ["id", "actor", "verb", "moment_id", "comment_id", "is_read", "created_at"]
+        read_only_fields = fields

api/apps/notifications/signals.py

@@ -0,0 +1,49 @@
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+
+from apps.moments.models import Comment, Reaction
+
+from .models import Notification
+
+
+@receiver(post_save, sender=Reaction)
+def notify_on_reaction(sender, instance, created, **kwargs):
+    if not created:
+        return
+    moment = instance.moment
+    if instance.user_id == moment.owner_id:
+        return
+    Notification.objects.create(
+        recipient_id=moment.owner_id,
+        actor=instance.user,
+        verb=Notification.Verb.LIKE,
+        moment=moment,
+    )
+
+
+@receiver(post_save, sender=Comment)
+def notify_on_comment(sender, instance, created, **kwargs):
+    if not created:
+        return
+    moment = instance.moment
+
+    if instance.parent_id is None:
+        if instance.author_id != moment.owner_id:
+            Notification.objects.create(
+                recipient_id=moment.owner_id,
+                actor=instance.author,
+                verb=Notification.Verb.COMMENT,
+                moment=moment,
+                comment=instance,
+            )
+        return
+
+    parent_author_id = instance.parent.author_id
+    if instance.author_id != parent_author_id:
+        Notification.objects.create(
+            recipient_id=parent_author_id,
+            actor=instance.author,
+            verb=Notification.Verb.REPLY,
+            moment=moment,
+            comment=instance,
+        )

api/apps/notifications/urls.py

@@ -0,0 +1,8 @@
+from rest_framework.routers import DefaultRouter
+
+from .views import NotificationViewSet
+
+router = DefaultRouter()
+router.register("", NotificationViewSet, basename="notification")
+
+urlpatterns = router.urls

api/apps/notifications/views.py

@@ -0,0 +1,24 @@
+from rest_framework import mixins, permissions, viewsets
+from rest_framework.decorators import action
+from rest_framework.response import Response
+
+from .models import Notification
+from .serializers import NotificationSerializer
+
+
+class NotificationViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
+    serializer_class = NotificationSerializer
+    permission_classes = [permissions.IsAuthenticated]
+
+    def get_queryset(self):
+        return Notification.objects.filter(recipient=self.request.user).select_related("actor", "moment")
+
+    @action(detail=False, methods=["get"], url_path="unread-count")
+    def unread_count(self, request):
+        count = self.get_queryset().filter(is_read=False).count()
+        return Response({"unread_count": count})
+
+    @action(detail=False, methods=["post"], url_path="mark-read")
+    def mark_read(self, request):
+        self.get_queryset().filter(is_read=False).update(is_read=True)
+        return Response(status=204)

api/config/__init__.py

@@ -0,0 +1,3 @@
+from .celery import app as celery_app
+
+__all__ = ("celery_app",)

api/config/asgi.py

@@ -0,0 +1,7 @@
+import os
+
+from django.core.asgi import get_asgi_application
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
+
+application = get_asgi_application()

api/config/celery.py

@@ -0,0 +1,9 @@
+import os
+
+from celery import Celery
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
+
+app = Celery("aurora_moments")
+app.config_from_object("django.conf:settings", namespace="CELERY")
+app.autodiscover_tasks()

api/config/settings.py

@@ -0,0 +1,146 @@
+from datetime import timedelta
+from pathlib import Path
+
+import environ
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+env = environ.Env(
+    DEBUG=(bool, False),
+)
+environ.Env.read_env(BASE_DIR / ".env")
+
+SECRET_KEY = env("DJANGO_SECRET_KEY", default="insecure-dev-key-change-me")
+DEBUG = env("DEBUG")
+ALLOWED_HOSTS = env.list("DJANGO_ALLOWED_HOSTS", default=["*"])
+
+INSTALLED_APPS = [
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    "rest_framework",
+    "rest_framework_simplejwt",
+    "corsheaders",
+    "django_filters",
+    "apps.core",
+    "apps.accounts",
+    "apps.library",
+    "apps.moments",
+    "apps.notifications",
+]
+
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "corsheaders.middleware.CorsMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django.contrib.messages.middleware.MessageMiddleware",
+    "django.middleware.clickjacking.XFrameOptionsMiddleware",
+]
+
+ROOT_URLCONF = "config.urls"
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.debug",
+                "django.template.context_processors.request",
+                "django.contrib.auth.context_processors.auth",
+                "django.contrib.messages.context_processors.messages",
+            ],
+        },
+    },
+]
+
+WSGI_APPLICATION = "config.wsgi.application"
+ASGI_APPLICATION = "config.asgi.application"
+
+DATABASES = {
+    "default": env.db("DATABASE_URL", default="postgres://aurora:aurora@postgres:5432/aurora_moments"),
+}
+
+AUTH_USER_MODEL = "accounts.User"
+
+AUTH_PASSWORD_VALIDATORS = [
+    {"NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator"},
+    {"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator"},
+    {"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"},
+    {"NAME": "django.contrib.auth.password_validation.NumericPasswordValidator"},
+]
+
+LANGUAGE_CODE = "en-us"
+TIME_ZONE = "UTC"
+USE_I18N = True
+USE_TZ = True
+
+STATIC_URL = "static/"
+STATIC_ROOT = BASE_DIR / "staticfiles"
+
+# --- Media storage ---------------------------------------------------------
+# Default: local filesystem, mounted as a volume so it can point at a NAS
+# path in self-hosted deployments. Set MEDIA_BACKEND=s3 to switch to any
+# S3-compatible object store (AWS S3, MinIO, Backblaze B2, etc.) without
+# code changes.
+MEDIA_BACKEND = env("MEDIA_BACKEND", default="filesystem")
+
+if MEDIA_BACKEND == "s3":
+    STORAGES = {
+        "default": {"BACKEND": "storages.backends.s3.S3Storage"},
+        "staticfiles": {"BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage"},
+    }
+    AWS_ACCESS_KEY_ID = env("AWS_ACCESS_KEY_ID", default="")
+    AWS_SECRET_ACCESS_KEY = env("AWS_SECRET_ACCESS_KEY", default="")
+    AWS_STORAGE_BUCKET_NAME = env("AWS_STORAGE_BUCKET_NAME", default="aurora-moments")
+    AWS_S3_ENDPOINT_URL = env("AWS_S3_ENDPOINT_URL", default=None)
+    AWS_S3_REGION_NAME = env("AWS_S3_REGION_NAME", default="us-east-1")
+    AWS_DEFAULT_ACL = None
+    AWS_QUERYSTRING_AUTH = False
+else:
+    STORAGES = {
+        "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
+        "staticfiles": {"BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage"},
+    }
+    MEDIA_URL = "media/"
+    MEDIA_ROOT = env("MEDIA_ROOT", default=str(BASE_DIR / "media"))
+
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+
+# --- DRF / auth --------------------------------------------------------
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": (
+        "rest_framework_simplejwt.authentication.JWTAuthentication",
+    ),
+    "DEFAULT_PERMISSION_CLASSES": (
+        "rest_framework.permissions.IsAuthenticated",
+    ),
+    "DEFAULT_FILTER_BACKENDS": (
+        "django_filters.rest_framework.DjangoFilterBackend",
+    ),
+    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
+    "PAGE_SIZE": 30,
+}
+
+SIMPLE_JWT = {
+    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=30),
+    "REFRESH_TOKEN_LIFETIME": timedelta(days=14),
+    "ROTATE_REFRESH_TOKENS": True,
+}
+
+CORS_ALLOWED_ORIGINS = env.list("CORS_ALLOWED_ORIGINS", default=["http://localhost:5173"])
+
+# --- Celery --------------------------------------------------------------
+CELERY_BROKER_URL = env("REDIS_URL", default="redis://redis:6379/0")
+CELERY_RESULT_BACKEND = env("REDIS_URL", default="redis://redis:6379/0")
+CELERY_ACCEPT_CONTENT = ["json"]
+CELERY_TASK_SERIALIZER = "json"
+CELERY_RESULT_SERIALIZER = "json"
+CELERY_TIMEZONE = TIME_ZONE

api/config/urls.py

@@ -0,0 +1,18 @@
+from django.conf import settings
+from django.conf.urls.static import static
+from django.contrib import admin
+from django.urls import include, path
+from rest_framework_simplejwt.views import TokenObtainPairView, TokenRefreshView
+
+urlpatterns = [
+    path("admin/", admin.site.urls),
+    path("api/auth/token/", TokenObtainPairView.as_view(), name="token_obtain_pair"),
+    path("api/auth/token/refresh/", TokenRefreshView.as_view(), name="token_refresh"),
+    path("api/accounts/", include("apps.accounts.urls")),
+    path("api/library/", include("apps.library.urls")),
+    path("api/moments/", include("apps.moments.urls")),
+    path("api/notifications/", include("apps.notifications.urls")),
+]
+
+if settings.DEBUG and settings.MEDIA_BACKEND == "filesystem":
+    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

api/config/wsgi.py

@@ -0,0 +1,7 @@
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
+
+application = get_wsgi_application()

api/manage.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+import os
+import sys
+
+
+def main():
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError as exc:
+        raise ImportError(
+            "Couldn't import Django. Are you sure it's installed and "
+            "available on your PYTHONPATH environment variable? Did you "
+            "forget to activate a virtual environment?"
+        ) from exc
+    execute_from_command_line(sys.argv)
+
+
+if __name__ == "__main__":
+    main()

api/requirements.txt

@@ -0,0 +1,13 @@
+Django==5.0.9
+djangorestframework==3.15.2
+djangorestframework-simplejwt==5.3.1
+django-cors-headers==4.4.0
+django-environ==0.11.2
+django-filter==24.3
+psycopg[binary]==3.2.3
+celery==5.4.0
+redis==5.0.8
+Pillow==10.4.0
+django-storages==1.14.4
+boto3==1.35.36
+gunicorn==23.0.0