feat(notifications): implement transactional email notification system

.github/workflows/tests.yml

@@ -0,0 +1,55 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: [develop, main]
+
+concurrency:
+  group: tests-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_DB: fiesta
+          POSTGRES_USER: fiesta
+          POSTGRES_PASSWORD: fiesta
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U fiesta"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=5
+
+    env:
+      DATABASE_URL: postgres://fiesta:fiesta@localhost:5432/fiesta
+      DJANGO_SETTINGS_MODULE: fiesta.settings
+      DJANGO_CONFIGURATION: Development
+      DJANGO_SECRET_KEY: ci-test-secret-key-not-for-production
+      DJANGO_RECAPTCHA_SITE_KEY: dummy-recaptcha-site-key
+      DJANGO_RECAPTCHA_SECRET_KEY: dummy-recaptcha-secret-key
+      ROOT_DOMAIN: fiesta.test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        working-directory: fiesta
+        run: uv run python manage.py test --verbosity 1

Dockerfile

@@ -110,8 +110,8 @@ ENV UV_PROJECT_ENVIRONMENT=/venv
 COPY pyproject.toml uv.lock ./
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv sync ${UV_SYNC_FLAGS} --no-install-project
-# seed setuptools into venv for pkg_resources compat
-RUN /venv/bin/pip install setuptools
+# seed setuptools into venv for pkg_resources compat (setuptools<72 ships pkg_resources)
+RUN uv pip install --python /venv/bin/python "setuptools<72"
 
 # base runtime image
 FROM ${PYTHON_IMAGE} as web-base

Makefile

@@ -18,7 +18,7 @@ ARG =
 
 MODELS_PNG = models.png
 GRAPH_MODELS_CMD = graph_models accounts plugins auth sections events \
-	universities esncards buddy_system \
+	universities esncards buddy_system pickup_system notifications \
 	--verbose-names --disable-sort-fields \
 	--pydot -X 'ContentType|Base*Model' \
 	 -g -o $(MODELS_PNG)

docker-compose.override.yml

@@ -1,4 +1,3 @@
-version: '3.3'
 services:
   web:
 #    environment:
@@ -30,6 +29,9 @@ services:
       - webpack_build:/usr/src/build
 
   dockerproxy:
+    labels:
+      dev.orbstack.domains: "*.${ROOT_DOMAIN},${ROOT_DOMAIN}"
+      dev.orbstack.http-port: 80
     environment:
       - DISABLE_ACCESS_LOGS=1
     volumes:

docker-compose.prod.yml

@@ -1,4 +1,3 @@
-version: '3.3'
 services:
   web:
     build:

docker-compose.yml

@@ -1,4 +1,4 @@
-version: '3.3'
+name: fiesta-plus
 services:
   web:
     command: python manage.py runserver 0.0.0.0:8000

fiesta/apps/accounts/migrations/0028_add_email_notifications_enabled.py

@@ -0,0 +1,18 @@
+# Generated by Django 4.2.28 on 2026-03-06 23:52
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('accounts', '0027_userprofile_picture_height_userprofile_picture_width_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='userprofile',
+            name='email_notifications_enabled',
+            field=models.BooleanField(default=True, verbose_name='email notifications'),
+        ),
+    ]

fiesta/apps/accounts/models/profile.py

@@ -165,6 +165,7 @@ class Preferences(enum.Flag):
 
     # TODO: define formfield/widget to handle flagging
     preferences = models.PositiveSmallIntegerField(default=0, verbose_name=_("user preferences as flags"))
+    email_notifications_enabled = models.BooleanField(default=True, verbose_name=_("email notifications"))
 
     State = UserProfileState
 

fiesta/apps/accounts/templates/accounts/user_profile/base.html

@@ -85,6 +85,23 @@
             Social Accounts
           </a>
         </li>
+        {% if request.in_space_of_section %}
+          <li>
+            <a href="{% url "notifications:preferences" %}">
+              <svg class="h-5 w-5"
+                   fill="none"
+                   stroke="currentColor"
+                   stroke-width="2"
+                   viewBox="0 0 24 24"
+                   xmlns="http://www.w3.org/2000/svg"
+                   aria-hidden="true">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M14.857 17.082a23.848 23.848 0 005.454-1.31A8.967 8.967 0 0118 9.75v-.7V9A6 6 0 006 9v.75a8.967 8.967 0 01-2.312 6.022c1.733.64 3.56 1.085 5.455 1.31m5.714 0a24.255 24.255 0 01-5.714 0m5.714 0a3 3 0 11-5.714 0">
+                </path>
+              </svg>
+              {% trans "Notifications" %}
+            </a>
+          </li>
+        {% endif %}
       </ul>
     </div>
     <div class="w-full md:w-3/4">

fiesta/apps/buddy_system/migrations/0032_add_email_notification_fields.py

@@ -0,0 +1,24 @@
+# Generated by Django 4.2.28 on 2026-03-03 14:17
+
+import datetime
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('buddy_system', '0031_alter_buddysystemconfiguration_rolling_limit_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='buddysystemconfiguration',
+            name='email_notify_issuer_delay',
+            field=models.DurationField(default=datetime.timedelta(seconds=3600), help_text='Gives editors time to correct the match before the student is notified.', verbose_name='Delay before notifying the issuer'),
+        ),
+        migrations.AddField(
+            model_name='buddysystemconfiguration',
+            name='email_notify_on_match',
+            field=models.BooleanField(default=True, verbose_name='Send email notifications on match'),
+        ),
+    ]

fiesta/apps/buddy_system/models/configuration.py

@@ -34,6 +34,16 @@ class BuddySystemConfiguration(BaseRequestSystemConfiguration):
         help_text=MatchingPoliciesRegister.DESCRIPTION,
     )
 
+    email_notify_on_match = models.BooleanField(
+        default=True,
+        verbose_name=_("Send email notifications on match"),
+    )
+    email_notify_issuer_delay = models.DurationField(
+        default=datetime.timedelta(hours=1),
+        verbose_name=_("Delay before notifying the issuer"),
+        help_text=_("Gives editors time to correct the match before the student is notified."),
+    )
+
     @property
     def matching_policy_instance(self) -> BaseMatchingPolicy:
         return MatchingPoliciesRegister.get_policy(self)

fiesta/apps/buddy_system/views/editor.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import logging
+
 from django.contrib.messages.views import SuccessMessageMixin
 from django.urls import reverse, reverse_lazy
 from django.utils.translation import gettext_lazy as _
@@ -19,6 +21,8 @@
 from apps.utils.breadcrumbs import with_breadcrumb, with_object_breadcrumb, with_plugin_home_breadcrumb
 from apps.utils.views import AjaxViewMixin
 
+logger = logging.getLogger(__name__)
+
 
 class BuddyRequestsTable(BaseRequestsTable):
     match_request = TemplateColumn(
@@ -91,6 +95,18 @@ class QuickBuddyMatchView(BaseQuickRequestMatchView):
     form_url = "buddy_system:quick-match"
     match_model = BuddyRequestMatch
 
+    def after_match_created(self, match, fiesta_request) -> None:
+        from apps.notifications.services.match import notify_buddy_match
+
+        try:
+            notify_buddy_match(
+                match=match,
+                request=fiesta_request,
+                section=self.request.in_space_of_section,
+            )
+        except Exception:
+            logger.exception("Failed to send buddy match notification for match pk=%s", match.pk)
+
 
 class UpdateBuddyRequestStateView(BaseUpdateRequestStateView):
     model = BuddyRequest

fiesta/apps/buddy_system/views/matching.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import logging
+
 from django.contrib.auth.mixins import PermissionRequiredMixin
 from django.template.loader import render_to_string
 from django.urls import reverse_lazy
@@ -18,6 +20,8 @@
 from apps.sections.views.mixins.section_space import EnsureInSectionSpaceViewMixin
 from apps.utils.breadcrumbs import with_breadcrumb, with_plugin_home_breadcrumb
 
+logger = logging.getLogger(__name__)
+
 
 @with_plugin_home_breadcrumb
 @with_breadcrumb(_("Waiting Requests"))
@@ -94,6 +98,18 @@ def get_form(self, form_class=None):
         )
         return form
 
+    def after_match_created(self, match, fiesta_request) -> None:
+        from apps.notifications.services.match import notify_buddy_match
+
+        try:
+            notify_buddy_match(
+                match=match,
+                request=fiesta_request,
+                section=self.request.in_space_of_section,
+            )
+        except Exception:
+            logger.exception("Failed to send buddy match notification for match pk=%s", match.pk)
+
 
 class ServeFilesFromBuddiesMixin:
     @classmethod

fiesta/apps/dashboard/models/configuration.py

@@ -6,7 +6,6 @@
 
 
 class DashboardConfiguration(BasePluginConfiguration):
-
     class Meta:
         verbose_name = _("dashboard configuration")
         verbose_name_plural = _("dashboard configurations")

fiesta/apps/fiestarequests/views/editor.py

@@ -51,6 +51,9 @@ def get_initial(self):
         except ObjectDoesNotExist:
             return {}
 
+    def after_match_created(self, match, fiesta_request) -> None:
+        """Hook for subclasses to trigger notifications after a match is created."""
+
     @transaction.atomic
     def form_valid(self, form):
         br: BaseRequestProtocol | models.Model = form.instance
@@ -64,17 +67,19 @@ def form_valid(self, form):
 
         matcher: User = form.cleaned_data.get("matcher")
 
-        match = self.match_model(
+        new_match = self.match_model(
             request=br,
             matcher=matcher,
             matcher_faculty=matcher.profile_or_none.faculty,
         )
 
-        match.save()
+        new_match.save()
 
         br.state = BaseRequestProtocol.State.MATCHED
         br.save(update_fields=["state"])
 
+        transaction.on_commit(lambda: self.after_match_created(new_match, br))
+
         return super().form_valid(form)
 
 
@@ -108,6 +113,9 @@ def form_valid(self, form: ModelForm):
 
         # TODO: django.lifecycle would be probably better
         if before == BaseRequestProtocol.State.MATCHED and after == BaseRequestProtocol.State.CREATED:
+            from apps.notifications.services.scheduler import cancel_scheduled_notifications_for
+
+            cancel_scheduled_notifications_for(self.object.match)
             self.object.match.delete()
 
         return resp

fiesta/apps/fiestarequests/views/matching.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from django.contrib.messages.views import SuccessMessageMixin
-from django.db import models
+from django.db import models, transaction
 from django.shortcuts import get_object_or_404
 from django.urls import reverse
 from django.utils.translation import gettext as _
@@ -56,6 +56,10 @@ def get_context_data(self, **kwargs):
         data["form_url"] = reverse(self.form_url, kwargs={"pk": self.fiesta_request.pk})
         return data
 
+    def after_match_created(self, match, fiesta_request) -> None:
+        """Hook for subclasses to trigger notifications after a match is created."""
+
+    @transaction.atomic
     def form_valid(self, form):
         match: BaseRequestMatchProtocol = form.instance
         match.request = self.fiesta_request
@@ -68,4 +72,6 @@ def form_valid(self, form):
         self.fiesta_request.state = BaseRequestProtocol.State.MATCHED
         self.fiesta_request.save(update_fields=["state"])
 
+        transaction.on_commit(lambda: self.after_match_created(match, self.fiesta_request))
+
         return response

fiesta/apps/notifications/admin.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.contrib import admin
+from django.utils import timezone
+from django.utils.translation import gettext_lazy as _
+
+from apps.notifications.models import ScheduledNotification, SectionNotificationPreferences
+
+if TYPE_CHECKING:
+    from django.db.models import QuerySet
+    from django.http import HttpRequest
+
+
+@admin.register(SectionNotificationPreferences)
+class SectionNotificationPreferencesAdmin(admin.ModelAdmin):
+    list_display = ["user", "section", "notify_on_match", "notify_on_new_member_waiting", "created"]
+    list_filter = ["section", "notify_on_match", "notify_on_new_member_waiting"]
+    # user is FK → accounts.User
+    search_fields = ["user__email", "user__first_name", "user__last_name", "section__name"]
+    readonly_fields = ["created", "modified"]
+
+
+@admin.register(ScheduledNotification)
+class ScheduledNotificationAdmin(admin.ModelAdmin):
+    list_display = ["kind", "recipient", "section", "send_after", "sent_at", "cancelled_at", "created"]
+    list_filter = ["kind", "section"]
+    # recipient is FK to accounts.User
+    search_fields = ["recipient__email", "recipient__first_name", "recipient__last_name"]
+    readonly_fields = ["created", "modified", "content_type", "object_id", "content_object"]
+    date_hierarchy = "send_after"
+    actions = ["mark_as_sent", "cancel_notifications"]
+
+    def get_queryset(self, request: HttpRequest) -> QuerySet[ScheduledNotification]:
+        return super().get_queryset(request).select_related("recipient", "section", "content_type")
+
+    @admin.action(description=_("Send now (bypass send_after)"))
+    def mark_as_sent(self, request: HttpRequest, queryset: QuerySet[ScheduledNotification]) -> None:
+        updated = queryset.filter(sent_at__isnull=True, cancelled_at__isnull=True).update(send_after=timezone.now())
+        self.message_user(request, _("Scheduled %s notification(s) to send immediately.") % updated)
+
+    @admin.action(description=_("Cancel selected notifications"))
+    def cancel_notifications(self, request: HttpRequest, queryset: QuerySet[ScheduledNotification]) -> None:
+        count = 0
+        for notification in queryset.filter(sent_at__isnull=True, cancelled_at__isnull=True):
+            notification.cancel()
+            notification.save(update_fields=["cancelled_at", "modified"])
+            count += 1
+        self.message_user(request, _("Cancelled %s notification(s).") % count)