I Built a Real-Time Notification System Inspired by Accra Traffic

I want to start this with something that has nothing to do with code.
If you've been in traffic in Accra, Ghana — specifically at one of those busy intersections with police officers manually directing — you've probably experienced this: one officer clears their side and cars start moving. But nobody told the officer on the perpendicular road. So now that road is blocked. And the one behind it. And suddenly the congestion you were trying to fix is worse than before.
The problem isn't effort. The officers are working hard. The problem is communication. There's no real-time coordination between them.
That frustration is what I kept thinking about while building my latest backend project.

What I Built

A real-time, event-driven notification platform. The core idea: any service or system can fire an event to a REST endpoint, and the right subscribers receive a notification instantly through a WebSocket connection. No polling. No refresh. Just live updates the moment something happens.
To make it visual and relatable, I built a traffic command center frontend that demonstrates it. You can fire events like CONGESTION_DETECTED, ACCIDENT_REPORTED, or LIGHT_MALFUNCTION, and watch traffic lights at a simulated intersection respond in real time while notifications arrive in a live feed.

The Architecture

The system has five main layers working together:

1. Event Ingestion (Django REST Framework) Any client — authenticated user or external service — can POST to /api/events/. The serializer validates the payload, checks that either a user or a source identifier is present, and saves the event to the database.
2. Message Bus (Apache Kafka + aiokafka) After the event saves, a service layer serializes it and publishes it to a Kafka topic called events using aiokafka's async producer. This is where the system becomes event-driven — the API's job ends here. Everything that happens next is decoupled.
3. Consumer (aiokafka Consumer) A separate long-running async process reads from the events topic. For each message it queries NotificationPreference to find users who have that event type enabled, creates Notification records, then routes delivery based on online status.
4. Real-Time Delivery (Django Channels + Redis) Connected users join a WebSocket group named after their user ID. When the consumer pushes to that group via the Redis channel layer, Django Channels delivers it to every active WebSocket connection for that user. Instant.
5. Offline Tracking (Redis Middleware) Custom middleware updates a Redis set on every HTTP request to track which users are currently active. TTL keys auto-expire after 5 minutes of inactivity. Clean, automatic, no cron jobs needed.

The Async/Sync Bridge Problem

This was the hardest conceptual challenge. Django is synchronous. aiokafka is fully async. Django ORM is sync. Kafka consumers are async.
Two patterns solved it:
For calling async Kafka code from sync Django views:

asyncio.run(send_one(data))

For calling sync Django ORM from inside async Kafka consumers:

result = await sync_to_async(lambda: list(
    NotificationPreference.objects.filter(enabled=True, event_type=event_type)
    .values_list('user', flat=True)
))()

The list() inside the lambda is important — Django querysets are lazy. Without forcing evaluation inside sync_to_async, the queryset hits the database in async context and crashes.

The Traffic Control Demo

The frontend is a standalone HTML file. No framework, no build step. Two panels — an event firing board on the left with buttons for different traffic events, and a live notification feed on the right that updates in real time via WebSocket.
When you fire an ACCIDENT event, all four traffic lights at the simulated intersection turn red. CONGESTION turns them amber. Route cleared turns them green. It's not a real traffic system — but it demonstrates exactly the coordination problem I described at the start. One event, every connected client knows immediately.

What's Next

The pipeline works end to end. What's still to build:

JWT authentication so external services can connect securely
Celery for offline delivery — queue notifications for users who aren't connected and deliver when they reconnect
AWS deployment with Terraform and GitHub Actions CI/CD

I'm almost 2 years into coding, entirely self-taught. This is the most complex system I've put together. The architecture concepts — event-driven design, message brokers, async processing, WebSocket delivery — were things I understood theoretically before building this. Actually wiring them together and debugging the places where sync meets async is a completely different experience.

If you're building something similar or have questions about the architecture, drop a comment. I'm still learning and always happy to talk through it.

GitHub: Real Time Notification System