Background Tasks and Browser Notifications¶
notes_chat_app implements its reminder system on two levels: a background email worker (Celery) and browser polling with a Bootstrap Toast.
The problem and the solution¶
A Django view cannot send an email exactly at the scheduled time: it runs only in response to an HTTP request. If the browser is not open, the reminder will not fire.
Solution: the Celery Worker, a separate process that is always active and runs tasks independently of the browser.
Architecture¶
flowchart TD
Beat["Celery Beat<br>(every 60 sec)"] -->|task name + args| Broker
Broker["Redis DB 1<br>(broker / result backend)"] -->|task message| Worker
Worker["Celery Worker<br>(concurrency=2)"] -->|send_mail| Email["Email<br>(console in dev)"]
Worker -->|is_sent=True| DB[("PostgreSQL")]
Worker -->|create next Reminder| DB
Browser["Browser JS<br>(every 60 sec)"] -->|GET /reminders/check/| Django
Django["Django view<br>reminders_check()"] -->|SELECT| DB
Django -->|JSON| Browser
Browser -->|Bootstrap Toast| User["👤 User"]
classDef step fill:#eceff1,stroke:#546e7a,stroke-width:1px;
classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
class Beat,Broker,Worker,DB,Browser,Django step;
class Email,User success;
Files¶
| File | Role |
|---|---|
notes_project/celery.py |
Initializes the Celery app, autodiscovers tasks |
notes_project/__init__.py |
Registers celery_app when Django starts |
notes_project/settings.py |
CELERY_BROKER_URL, CELERY_BEAT_SCHEDULE, CELERY_* |
notes_app/tasks.py |
@shared_task send_reminder_notifications() |
notes_app/selectors.py |
get_due_reminders_for_browser(user) |
notes_app/views.py |
reminders_check(request) → JsonResponse |
notes_app/urls.py |
path('reminders/check/', ...) |
notes_app/static/notes_app/js/reminders.js |
fetch polling + Bootstrap Toast |
templates/base.html |
toast-container + <script> for authenticated users |
docker-compose.yml |
the celery-worker and celery-beat services |
notes_app/tests/test_tasks.py |
unit tests for the task and the view |
notes_app/tests/test_selenium.py |
E2E test for the Toast appearing |
Celery Flow¶
1. Initialization¶
# notes_project/celery.py
import os
from celery import Celery
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'notes_project.settings')
app = Celery('notes_project')
app.config_from_object('django.conf:settings', namespace='CELERY')
app.autodiscover_tasks()
2. The task¶
# notes_app/tasks.py
@shared_task
def send_reminder_notifications():
from .models import Reminder
now = timezone.now()
pending = (
Reminder.objects
.select_related('note__user')
.filter(remind_at__lte=now, is_sent=False)
)
for reminder in pending:
user = reminder.note.user
if user.email:
send_mail(...)
reminder.is_sent = True
reminder.save(update_fields=['is_sent'])
_schedule_next(reminder)
3. Repeating reminders¶
def _schedule_next(reminder):
if reminder.repeat_pattern == 'none':
return
from dateutil.relativedelta import relativedelta
delta_map = {
'daily': relativedelta(days=1),
'weekly': relativedelta(weeks=1),
'monthly': relativedelta(months=1), # preserves the correct month length
}
delta = delta_map.get(reminder.repeat_pattern)
if delta:
Reminder.objects.create(
note=reminder.note,
remind_at=reminder.remind_at + delta,
message=reminder.message,
is_sent=False,
repeat_pattern=reminder.repeat_pattern,
)
relativedelta (from python-dateutil) correctly handles different month lengths, unlike timedelta(days=30).
4. The schedule (Beat)¶
# notes_project/settings.py
CELERY_BEAT_SCHEDULE = {
"send-reminders-every-minute": {
"task": "notes_app.tasks.send_reminder_notifications",
"schedule": 60.0,
},
}
5. Docker services¶
celery-worker:
build: .
command: celery -A notes_project worker -l info --concurrency=2
celery-beat:
build: .
command: celery -A notes_project beat -l info
There is always exactly one Beat instance. The Worker can scale horizontally.
Redis DB allocation¶
| Service | URL | Usage |
|---|---|---|
| Django Channels | redis://redis:6379/0 |
channel layer (WebSocket) |
| Celery | redis://redis:6379/1 |
broker + result backend |
# settings.py
_CELERY_REDIS = _REDIS_URL.replace("/0", "/1") if _REDIS_URL else "redis://localhost:6379/1"
CELERY_BROKER_URL = _CELERY_REDIS
CELERY_RESULT_BACKEND = _CELERY_REDIS
Separate DBs rule out conflicts between Channels and Celery.
Browser Notification Flow¶
Selector¶
# notes_app/selectors.py
def get_due_reminders_for_browser(user):
now = timezone.now()
return list(
Reminder.objects
.filter(
note__user=user,
remind_at__lte=now,
remind_at__gte=now - timedelta(hours=1), # display window: 1 hour
)
.select_related('note')
.order_by('remind_at')
.values('id', 'message', 'remind_at', 'note__title')
)
The 1-hour window: a user who opens the browser 40 minutes after a reminder will still see the Toast.
View¶
# notes_app/views.py
@login_required
def reminders_check(request):
data = selectors.get_due_reminders_for_browser(request.user)
for item in data:
item['remind_at'] = item['remind_at'].strftime('%d.%m.%Y %H:%M')
return JsonResponse({'reminders': data})
JS module¶
| Component | Purpose |
|---|---|
POLL_INTERVAL = 60_000 |
check every minute |
sessionStorage |
deduplication: a Toast is not repeated within the current session |
escapeHtml() |
XSS protection before inserting into the DOM |
checkReminders() |
async fetch → parse → showToast for new ones |
DOMContentLoaded |
the first check runs immediately on page load |
bootstrap.Toast |
Bootstrap 5 API: new bootstrap.Toast(el, {delay: 8000}).show() |
WebSocket vs Polling comparison¶
| Criterion | WebSocket (chat) | HTTP Polling (reminders) |
|---|---|---|
| Persistent connection | yes | no |
| Ideal for | a live data stream | rare events (1/min) |
| Complexity | higher (ASGI, consumer) | lower (one endpoint) |
| Server load | low (push) | depends on the interval |
| Suitable for reminders | overkill | yes |
Testing¶
The task¶
# test_tasks.py — key tests
@override_settings(EMAIL_BACKEND='django.core.mail.backends.locmem.EmailBackend')
def test_marks_due_reminder_as_sent(self):
r = self._reminder(offset_minutes=-5)
send_reminder_notifications()
r.refresh_from_db()
self.assertTrue(r.is_sent)
def test_ignores_future_reminders(self):
r = self._reminder(offset_minutes=+10)
send_reminder_notifications()
r.refresh_from_db()
self.assertFalse(r.is_sent)
def test_daily_repeat_creates_next_reminder(self):
r = self._reminder(offset_minutes=-5, repeat='daily')
original_at = r.remind_at
send_reminder_notifications()
next_r = Reminder.objects.filter(note=self.note, is_sent=False).first()
diff = (next_r.remind_at - original_at).total_seconds()
self.assertAlmostEqual(diff, 86400, delta=60)
override_settings(EMAIL_BACKEND='...locmem...') captures emails in django.core.mail.outbox without an SMTP server.
Selenium E2E¶
def test_toast_appears_for_due_reminder(self):
Reminder.objects.create(
note=self.note,
remind_at=timezone.now() - timedelta(minutes=30),
message='JS toast test',
)
self._login_via_cookie()
self.driver.get(f'{self.live_server_url}/notes/')
# JS calls checkReminders() immediately on DOMContentLoaded
toast = WebDriverWait(self.driver, 10).until(
EC.presence_of_element_located((By.CSS_SELECTOR, '.toast.show'))
)
self.assertIn('Selenium Reminder Note', toast.text)
The test does not wait 60 seconds: checkReminders() runs right after the DOM loads.
Coverage¶
| File | Class | Count | What it tests |
|---|---|---|---|
test_tasks.py |
SendReminderTaskTest |
8 | the task, email, repeat_pattern |
test_tasks.py |
RemindersCheckViewTest |
5 | JSON endpoint, auth, isolation |
test_selenium.py |
SeleniumReminderToastTest |
4 | the Toast appears / does not appear |
Running:
# Unit
docker compose run --rm web python manage.py test notes_app.tests.test_tasks -v 2
# Selenium (requires the running stack)
docker compose up -d
docker compose exec web python manage.py test \
notes_app.tests.test_selenium.SeleniumReminderToastTest -v 2
Common pitfalls¶
| Situation | Error | Solution |
|---|---|---|
Two celery-beat instances |
every reminder is sent twice | Beat must be exactly 1 process |
| Celery and Channels in Redis DB 0 | key conflicts | Celery → DB 1 |
timedelta(days=30) for a month |
January 31 + 30 days = March 1 in a leap year (March 2 in a common year) — February is skipped | relativedelta(months=1) |
Lazy QuerySet in get_due_reminders_for_browser |
SynchronousOnlyOperation when called from async code |
list(queryset.values(...)) |
| Emails in tests go to a real server | unexpected sends during CI | @override_settings(EMAIL_BACKEND='...locmem...') |
| The Toast appears several times | the interval fires before it is hidden | sessionStorage deduplication by id |