Project context

Many web chat applications rely on single-page JavaScript frontends (such as React or Vue) paired with separate backend APIs. Chattfy was built to test a different architecture: building a responsive, real-time messaging system using server-side Python, Django templates, and lightweight client-side tooling.

By combining Django Channels for asynchronous WebSocket handling and HTMX for HTML fragment swapping, the application achieves real-time communication without requiring a complex client-side state management layer

Architecture and real-time communication

The backend uses an ASGI setup running through Django Channels. When a user opens a chat room, the browser establishes a persistent WebSocket connection directly with the server.

Message delivery flows through several discrete steps:

1. A client submits a message or file attachment through an HTMX-powered form.
2. The request reaches ChatroomConsumer, a Channels consumer that validates room membership and user credentials.
3. The consumer sends the event to the configured channel layer, which broadcasts the payload to all sockets subscribed to that room group.
4. Instead of sending raw JSON and forcing the client to construct DOM nodes, the server renders the message template directly to an HTML string (render_to_string).
5. HTMX intercepts the incoming HTML fragment over the WebSocket and inserts it into the active conversation container.

Application features

Chattfy includes both group and direct messaging capabilities:

• Public rooms and private chats -> Users can create public group rooms with generated identifiers via shortuuid, or initiate direct one-on-one conversations
• Online presence tracking: The ChatGroup model maintains an active many-to-many relationship with the user table (users_online). When sockets connect or disconnect, the consumer triggers an updated member count broadcast to the room.
• Media and file sharing: Users can upload images, PDFs, and general documents. File processing is handled with Pillow, and django-cleanup removes old files from disk when associated database records are updated or deleted.
• Room moderation: The room creator retains administrative permissions to rename the group, remove members, or delete the room.
• Authentication: Account creation, login workflows, and email verification are managed through django-allauth.

Tech stack

• Backend: Python, Django, Django Channels (ASGI), Daphne
• Real-time transport: WebSockets, Redis channel layer
• Frontend: Django templates, HTMX, Tailwind CSS
• Data storage: SQLite (local development), PostgreSQL compatibility

Demo: