django-channels-chat is a small Django chat that trades polling for a notification socket

A message center where the socket only says something changed

The project describes itself as a small functional person-to-person message center application built using Django, and the interesting design decision is visible in the first two lines of the architecture notes. It has a REST API, and it uses WebSockets to notify clients of new messages and avoid polling.

That is a hybrid design, and it is a good one to study. The socket does not carry message bodies. It carries a notification, in this case the ID of a new message, and the client then fetches the actual content with an ordinary GET against the REST API. One path handles state, the other handles change notification, and the split keeps the WebSocket layer small.

The alternative approach is a client that polls the REST API on a timer, which needs no WebSocket infrastructure at all but makes the server answer a question it already knows the answer to. The cost of the polling approach is wasted work on every idle user, and the cost of this one is the machinery of a channel layer, a separate process model and a Redis instance. The project is essentially a worked demonstration of why the machinery is worth it.

Four steps from sending a message to seeing it

The architecture section describes the data flow in enough detail to be reproducible, and it is worth reading as a sequence.

When a user logs in, the frontend downloads the user list and opens a WebSocket connection to the server, described as the notifications channel. When a user selects someone to chat with, the frontend downloads the latest fifteen messages they have exchanged, with the fifteen coming from a setting. When the user sends a message, the frontend posts to the REST API, Django saves the message, and Django notifies the users involved through the WebSocket connection by sending the new message ID. Finally, when the frontend receives that notification, it performs a GET query against the API to download the message itself.

Two things follow from that sequence. The server never pushes message content over the socket, so a slow or flaky socket degrades to delayed delivery rather than to a broken one, and the REST API stays the single authority on what a message is. It also means the notification path and the fetch path are separate, so a client that misses a notification can still recover by fetching, provided the client is written to do that. The project does not document such a recovery path.

The channel layer is described two different ways in the same README

Here the documentation is inconsistent, and anyone planning to deploy this should know it before reading further.

The scaling section quotes the Channels documentation on the multi-process model, explaining that instead of running everything in one process alongside a WSGI server, you run one or more interface servers and one or more worker servers connected by the configured channel layer. The author then says the in-memory channel system is in use here, but that it could be changed to the Redis backend to improve performance and spawn multiple workers in a distributed environment.

Later, an update dated 04/06/19 states that the project moved to Channels 2 and now uses Redis as the channel layer backing store, pointing at the channels_redis project for details. The same update records a move to pipenv for package management.

So the prose in the scaling section describes the in-memory option while the changelog note describes the Redis arrangement that the code is likely to use now. The in-memory channel layer is per-process, so with more than one worker the notifications would not reach clients attached to other workers. Redis is what makes the multi-worker story work. Check the channel layer setting in the chat folder before copying this configuration into a project with more than one process.

Running it needs pipenv, MySQL and Redis, in that order

The run section is a numbered sequence, and it needs a MySQL database and a running Redis server before anything useful happens.

The first two steps set up the Python environment and the dependencies, using pipenv with Python 3.

pipenv --python 3 shell
pipenv install

Then the database is created with the utf8 character set, and Redis is started as a separate process.

CREATE DATABASE chat CHARACTER SET utf8;

redis-server

With the infrastructure in place, the schema is created and the test suite is run.

./manage.py migrate
./manage.py test

Finally an admin account is created and the development server is started.

./manage.py createsuperuser
./manage.py runserver

One configuration detail is worth noting for anyone who will run this past the demo stage. Settings are read from the chat folder, and a local_settings.py file in that folder overrides the defaults. The message prefetch count is one of those settings.

MESSAGES_TO_LOAD = 15

MySQL with indexes, and the sharding remark

The database section is short. MySQL is used for the demo, and the author notes that a MySQL cluster or shard could be deployed if more performance were required, with the aside that indexes are used to improve performance.

There is no schema in the repository listing to check that against, but the top level gives the shape: a manage.py entry point, a chat/ directory, a core/ directory, plus static/ and templates/ for the frontend. The split between chat and core suggests the messaging logic and the Django project configuration are separated, which is a reasonable arrangement to copy.

The MySQL choice is worth a second look for a modern deployment, since PostgreSQL is what most Django projects default to, and the project carries no PostgreSQL instructions. The author also mentions pipenv, and the repository includes a Pipfile and Pipfile.lock, so dependency versions are pinned at least at the time of that lock file.

The honest reading is that the database layer is the least developed part of this project. A message table with two participants and an ID, plus a query that fetches the last n messages for a pair, is the entire requirement, and the whole scheme is simple enough that the interesting engineering in this repository is elsewhere.

The author lists what the project does not have

The assumptions section is the most useful part of the documentation, because it is where the project says what it is not. The reason given is time constraints.

Missing are user sign-in and forgot password, user selector pagination, good test coverage, better comments and documentation strings, and frontend tests. Also missing are a modern frontend framework such as React, a frontend package with automatic linting, building and minification, and proper UX and UI design, with the note that it looks plain bootstrap.

Two of those omissions change how you should read the rest of the project. Without sign-in, the user list that the frontend downloads after login is populated by whatever the database happens to contain, which makes the authentication story something you have to build before the application is usable by anyone you do not control. Without pagination on the user selector, the entire user list is fetched at once, which is fine for a demo with a handful of accounts and a problem in a deployment with thousands.

The test coverage claim is consistent with the run section, which asks you to run ./manage.py test as a step. What runs there is the existing suite, which the author does not count as good coverage.

A Channels 2 era project with a recent commit

The project sits at an interesting point in time. The architecture and the Channels 2 update both date from 2019, when pipenv was the recommended way to manage Python dependencies and Django Channels was still commonly installed from source. The repository has no GitHub releases, so there is no tagged version to pin and no changelog beyond the inline update note.

The last push to the master branch was on 2026-08-18, so the code is not abandoned, but a single commit on a default branch is a thin basis for claiming the project is current. The frontend, if the project still has one, is the plain bootstrap version the author describes, with no build step and no modern framework. A framework-free frontend is a fine choice for a reference implementation and a poor choice for anything that will grow.

The licence is MIT, which is permissive and imposes no obligations on a derived work beyond including the licence text. For a sample application that teams copy pieces from, that matters. The practical question before adopting this code is not the licence but the gap between the demo and your requirements, and the assumptions section is an honest inventory of that gap.

Editorial conclusion

django-channels-chat suits a developer who wants a readable reference for wiring a REST API to a Channels notification channel, and it is the wrong base for a product chat because it has no sign-in flow and no user list pagination. Before building on it, read the scaling section closely, since the documentation describes an in-memory channel layer in one place and a Redis backing store in another, and confirm which one the code in the chat folder actually configures.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. narrowfail/django-channels-chat on GitHub
4. README