Notes Chat App — Deep Dive¶
notes_chat_app is the final project of the course, built on Django 5.2. It combines CRUD, group sharing of objects, a WebSocket chat, a full testing pyramid, and Docker Compose in a single codebase.
Navigation¶
| Document | Purpose |
|---|---|
| Project Overview | roles, stack, architectural patterns |
| Architecture | components, ASGI routing, layers, Docker |
| Domain Model | 10 models, ER diagram, fields, deletion behavior |
| Feature Map | what is implemented and where in the code |
| Request Flows | HTTP CRUD, auth, WebSocket flows (Mermaid) |
| Security Model | IDOR, Q-filter, group sharing, WebSocket auth |
| Async and Chat | ASGI, GroupChatConsumer, channel layer |
| Background Tasks | Celery Worker, Beat, email reminders, Browser Toast |
| Testing Strategy | 7 test files, 200+ tests, TransactionTestCase |
| Setup | running with Docker Compose |
| Deployment | Docker services, production checklist |
| Student Tasks | practical tasks at 3 levels |
Architecture at a glance¶
flowchart TD
Browser --> Nginx["Nginx :80<br>(reverse proxy, static)"]
Nginx -->|HTTP| Uvicorn["Uvicorn :8001<br>ASGI server"]
Nginx -->|WebSocket upgrade| Uvicorn
Uvicorn --> Router["ProtocolTypeRouter<br>notes_project/asgi.py"]
Router -->|http| HTTP["Django HTTP stack"]
Router -->|websocket| Auth["AuthMiddlewareStack<br>→ URLRouter"]
HTTP --> Views["views.py<br>(thin layer)"]
Views --> Forms["forms.py<br>(validation)"]
Views --> Sel["selectors.py<br>(read-only ORM)"]
Views --> Srv["services.py<br>(mutations)"]
Sel --> ORM["Django ORM"]
Srv --> ORM
ORM --> PG[("PostgreSQL :5432")]
Auth --> Consumer["GroupChatConsumer<br>consumers.py"]
Consumer -->|database_sync_to_async| ORM
Consumer -->|group_send| Redis[("Redis :6379<br>channel layer")]
Redis -->|chat_message| Consumer
classDef step fill:#eceff1,stroke:#546e7a,stroke-width:1px;
classDef decision fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
classDef warning fill:#fff8e1,stroke:#e65100,stroke-width:2px;
class Browser,Nginx,Uvicorn,HTTP,Forms,Sel,Srv,ORM,Auth,Consumer step;
class Router decision;
class PG,Redis success;
class Views warning;
File structure¶
notes_chat_app/
├── notes_project/ ← Django project package
│ ├── settings.py ← apps, DB, Channels, Redis, static, auth
│ ├── urls.py ← root URLs: admin, accounts, app include
│ ├── asgi.py ← ProtocolTypeRouter (http + websocket)
│ └── routing.py ← WebSocket URL: /ws/groups/<pk>/chat/
│
├── notes_app/ ← the single Django app
│ ├── models.py ← 10 models + constraints
│ ├── urls.py ← 35+ URL routes
│ ├── views.py ← FBV, @login_required, thin layer
│ ├── forms.py ← NoteForm, GroupCreateForm, ...
│ ├── selectors.py ← read-only QuerySets, access scoping
│ ├── services.py ← mutations: create/update/delete
│ ├── consumers.py ← GroupChatConsumer (AsyncWebsocketConsumer)
│ ├── tasks.py ← @shared_task send_reminder_notifications (Celery)
│ ├── admin.py ← model registration
│ └── tests/
│ ├── test_models.py
│ ├── test_services.py
│ ├── test_forms.py
│ ├── test_views.py
│ ├── test_consumers.py
│ ├── test_tasks.py
│ └── test_selenium.py
│
├── templates/ ← project-level templates
│ ├── base.html ← DOCTYPE, head, navbar, messages
│ └── layouts/
│ └── dashboard.html ← sidebar, content block
│
├── notes_app/templates/notes_app/ ← app-level templates
├── notes_app/static/notes_app/js/
│ ├── group_chat.js ← WebSocket JS client
│ └── reminders.js ← HTTP polling + Bootstrap Toast
│
├── nginx/
│ └── nginx.conf ← proxy_pass, WebSocket upgrade, static
├── docker-compose.yml ← db, redis, web, nginx, ngrok, selenium, celery-worker, celery-beat
├── Dockerfile
└── entrypoint.sh ← wait-for-db, migrate, collectstatic, seed
Layer model¶
HTTP Request
└─► notes_project/urls.py (include notes_app.urls)
└─► notes_app/urls.py (@login_required, path)
└─► views.py (coordination only)
├─► forms.py (validation, clean_*)
├─► selectors.py (scoped QuerySet — read)
└─► services.py (create/update/delete)
└─► models.py → PostgreSQL
Rule: views.py contains no ORM queries. selectors.py contains no mutations. services.py knows nothing about HTTP.
Domain Model¶
erDiagram
AUTH_USER ||--|| USER_PROFILE : "1:1 CASCADE"
AUTH_USER ||--o{ NOTEBOOK : "1:N CASCADE"
AUTH_USER ||--o{ NOTE : "1:N CASCADE"
AUTH_USER ||--o{ TAG : "1:N CASCADE"
AUTH_USER ||--o{ TODO_LIST : "1:N CASCADE"
AUTH_USER ||--o{ SHOPPING_LIST : "1:N CASCADE"
AUTH_USER ||--o{ CHAT_MESSAGE : "1:N CASCADE"
AUTH_GROUP ||--o{ NOTE : "FK SET_NULL"
AUTH_GROUP ||--o{ SHOPPING_LIST : "FK SET_NULL"
AUTH_GROUP ||--o{ CHAT_MESSAGE : "1:N CASCADE"
AUTH_USER }o--o{ TODO_LIST : "shared_with M2M"
AUTH_USER }o--o{ SHOPPING_LIST : "shared_with M2M"
NOTEBOOK ||--o{ NOTE : "FK SET_NULL"
NOTE }o--o{ TAG : "M2M"
NOTE ||--o{ REMINDER : "1:N CASCADE"
TODO_LIST ||--o{ TODO_ITEM : "1:N CASCADE"
SHOPPING_LIST ||--o{ SHOP_ITEM : "1:N CASCADE"
Key models¶
| Model | Specifics |
|---|---|
Note |
priority 1–4 (PositiveSmallIntegerField, CheckConstraint), group FK SET_NULL, notebook FK SET_NULL, tags M2M |
TodoList |
shared_with M2M(User) — shared access through direct sharing |
ShoppingList |
shared_with M2M(User) + group FK SET_NULL — two kinds of sharing |
ChatMessage |
author FK CASCADE, group FK CASCADE — no SET_NULL; when a group is deleted, its messages are deleted |
Reminder |
CASCADE from Note — when a note is deleted, its reminders are deleted |
UserProfile |
OneToOneField(User, CASCADE) — display_name(100), bio, avatar_url, timezone |
Deletion behavior¶
User deleted → all of their Note, Notebook, Tag, TodoList, ShoppingList, ChatMessage → CASCADE
Notebook deleted → Note.notebook → SET_NULL (notes are not deleted)
Note deleted → Reminder → CASCADE
Group deleted → Note.group → SET_NULL, ShoppingList.group → SET_NULL
→ ChatMessage → CASCADE (messages are deleted!)
TodoList deleted → TodoItem → CASCADE
ShoppingList deleted → ShopItem → CASCADE
URL routes¶
All routes are defined in notes_app/urls.py.
Notes¶
| URL | Name | View |
|---|---|---|
/notes/ |
note_list |
note_list |
/notes/new/ |
note_create |
note_create |
/notes/<pk>/ |
note_detail |
note_detail |
/notes/<pk>/edit/ |
note_edit |
note_edit |
/notes/<pk>/delete/ |
note_delete |
note_delete |
Todo¶
| URL | Name | View |
|---|---|---|
/todo/ |
todo_list |
todo_list_list |
/todo/new/ |
todo_create |
todo_list_create |
/todo/<pk>/ |
todo_detail |
todo_list_detail |
/todo/<pk>/share/ |
todo_share |
todo_list_share |
/todo/<pk>/items/add/ |
todo_item_add |
todo_item_add |
/todo/items/<pk>/toggle/ |
todo_item_toggle |
todo_item_toggle |
Shopping¶
| URL | Name | View |
|---|---|---|
/shopping/ |
shopping_list |
shopping_list_list |
/shopping/new/ |
shopping_create |
shopping_list_create |
/shopping/<pk>/share/ |
shopping_share |
shopping_list_share |
/shopping/<pk>/items/add/ |
shop_item_add |
shop_item_add |
/shopping/items/<pk>/toggle/ |
shop_item_toggle |
shop_item_toggle_purchased |
Groups and Chat¶
| URL | Name | View |
|---|---|---|
/groups/ |
group_list |
group_list |
/groups/new/ |
group_create |
group_create |
/groups/<pk>/ |
group_detail |
group_detail |
/groups/<pk>/delete/ |
group_delete |
group_delete |
/groups/<pk>/chat/ |
group_chat |
group_chat |
WebSocket¶
Defined in notes_project/routing.py.
Selectors¶
notes_app/selectors.py is the read-only ORM layer; it always returns materialized data or a QuerySet before rendering.
| Function | What it returns |
|---|---|
get_user_notes(user, *, archived, notebook, tag, search) |
QuerySet[Note] with select_related('notebook'), prefetch_related('tags') |
get_note_detail(user, note_id) |
Note or None (owner + group members) |
get_pinned_notes(user, limit=5) |
QuerySet[Note] |
get_user_notebooks(user) |
QuerySet[Notebook] |
get_user_tags(user) |
QuerySet[Tag] |
get_user_todo_lists(user) |
QuerySet[TodoList] (own) |
get_shared_todo_lists(user) |
QuerySet[TodoList] (shared_with) |
get_todo_list_detail(user, pk) |
TodoList or None |
get_user_shopping_lists(user) |
own shopping lists |
get_shared_shopping_lists(user) |
shared_with lists |
get_shopping_list_detail(user, pk) |
with group access |
get_user_groups(user) |
QuerySet[Group] where the user is a member |
get_group_with_members(group_id, user) |
group + prefetched members |
get_pending_reminders() |
reminders with remind_at <= now |
Access rule for shared objects:
# read: the owner OR a group member
Q(user=user) | Q(group__in=user.groups.all())
# write: the owner only
Q(user=user)
Services¶
notes_app/services.py contains mutating operations; they are called only after form validation.
Notes¶
create_note(*, user, title, content='', notebook=None, priority=1, group=None, tag_ids=None)
update_note(note, *, title=None, content=None, priority=None, notebook=None,
is_pinned=None, group=..., tag_ids=None)
delete_note(note)
toggle_pin_note(note) # flip is_pinned
archive_note(note) # is_archived = True
group=... (Ellipsis) in update_note is a sentinel meaning "do not change". group=None removes the group.
Notebooks, Tags¶
create_notebook(*, user, title, color='#4A90E2', is_default=False)
update_notebook(notebook, *, title, description='', color, is_default)
delete_notebook(notebook)
create_or_get_tag(*, user, name, color='#808080') # get_or_create
Todo¶
create_todo_list(*, user, title, description='')
share_todo_list(todo_list, username) # adds to shared_with
unshare_todo_list(todo_list, username)
add_todo_item(todo_list, *, text, due_date=None)
toggle_todo_item(item)
Shopping¶
create_shopping_list(*, user, title, store_name='', group=None)
share_shopping_list(shopping_list, username)
add_shop_item(shopping_list, *, name, quantity=1, unit='шт', estimated_price=None)
toggle_shop_item_purchased(item)
Groups¶
create_group(*, name, creator) # creates a Group + adds creator as a member
add_user_to_group(group, username)
GroupChatConsumer¶
notes_app/consumers.py contains the single WebSocket consumer.
class GroupChatConsumer(AsyncWebsocketConsumer):
async def connect(self) # auth + membership check → accept or close
async def disconnect(self, code) # group_discard
async def receive(self, text_data) # JSON parse → save_message → group_send
async def chat_message(self, event) # broadcast from the channel layer → send to the client
# sync helpers (called via database_sync_to_async)
def check_membership(self, group_pk, user) → bool
def load_history(self, group_pk) → list[dict] # the latest 50
def save_message(self, group_pk, user, content) → ChatMessage
ASGI import order (asgi.py):
# CORRECT: django.setup() → get_asgi_application() → import consumers
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'notes_project.settings')
django_asgi_app = get_asgi_application() # ← BEFORE any notes_app import
from notes_app.consumers import GroupChatConsumer # ← only AFTER
database_sync_to_async + materialization:
# ✅ correct: list() materializes the data before it leaves the worker
history = await database_sync_to_async(self.load_history)(group_pk)
def load_history(self, group_pk):
return list(
ChatMessage.objects.filter(group_id=group_pk)
.select_related('author')
.order_by('-created_at')[:50]
.values('content', 'author__username', 'created_at')
)
Security¶
IDOR protection¶
All object-level queries use a scoped queryset, never a bare .get(pk=pk):
# selectors.py
def get_note_detail(user, note_id):
user_groups = user.groups.all()
return Note.objects.filter(
Q(user=user) | Q(group__in=user_groups),
pk=note_id
).select_related('notebook', 'group').prefetch_related('tags').first()
If the result is None, the view returns Http404.
Permission matrix¶
| Object | Read | Write (edit/delete) |
|---|---|---|
| Note | owner + group members | owner only |
| Notebook | owner | owner |
| Tag | owner | owner |
| TodoList | owner + shared_with |
owner |
| ShoppingList | owner + shared_with + group |
owner |
| ChatMessage | group members (WS) | — |
WebSocket authentication¶
AuthMiddlewareStack reads the session cookie during the WS handshake → scope["user"].
The consumer checks user.is_authenticated and check_membership() in connect().
An unauthenticated user or a non-member → await self.close().
Testing pyramid¶
| File | Class | Count | What it tests |
|---|---|---|---|
test_models.py |
TestCase |
~25 | constraints, __str__, on_delete |
test_services.py |
TestCase |
~65 | return value + persistence |
test_forms.py |
TestCase |
~20 | valid/invalid data, clean_* |
test_views.py |
TestCase |
~85 | status codes, redirects, IDOR |
test_consumers.py |
TransactionTestCase |
~10 | WS connect, message, reject |
test_tasks.py |
TestCase |
~18 | Celery task, email, repeat, JSON view |
test_selenium.py |
StaticLiveServerTestCase / ChannelsLiveServerTestCase |
~23 | E2E flow + Toast notifications |
| Total | 200+ |
Why TransactionTestCase for consumers:
TestCase wraps each test in a transaction → rollback afterwards.
The async consumer reads the DB from a separate worker thread —
that thread does not see TestCase's uncommitted transaction.
→ setUp objects "disappear" for the consumer.
→ ALWAYS use TransactionTestCase for WebSocket tests.
Running:
# unit + integration + consumer
docker compose run --rm web python manage.py test \
notes_app.tests.test_models notes_app.tests.test_services \
notes_app.tests.test_forms notes_app.tests.test_views \
notes_app.tests.test_consumers -v 2
# Selenium (requires the running stack)
docker compose up -d
docker compose exec web python manage.py test notes_app.tests.test_selenium -v 2
Docker Compose¶
services:
db: # postgres:16-alpine, volume postgres_data
redis: # redis:7-alpine — DB 0: Channels, DB 1: Celery
web: # Django + Uvicorn :8001, depends on db + redis
nginx: # nginx:1.27-alpine, :80, proxy_pass to web, serves static
ngrok: # public HTTPS tunnel (development, profile tunnel)
selenium: # Selenium standalone Chrome for E2E tests (profile test)
selenium-tests: # runs test_selenium against selenium (profile test)
celery-worker: # runs @shared_task, --concurrency=2
celery-beat: # scheduler (exactly 1 instance), CELERY_BEAT_SCHEDULE
entrypoint.sh runs on every start:
# db and redis are already healthy (depends_on: condition: service_healthy)
python manage.py migrate --noinput
python manage.py collectstatic --noinput
[optional] python manage.py seed_demo_data --force
exec python -m uvicorn notes_project.asgi:application --host 0.0.0.0 --port 8001 --proxy-headers [--reload]
End-to-end scenario: Create Note¶
Browser views.py forms.py services.py PostgreSQL
| | | | |
|-- GET /notes/new/ ------>| | | |
|<---- NoteForm (empty) ---| | | |
| | | | |
|-- POST /notes/new/ ----->| | | |
| (title, content, tags) |-- NoteForm(data) -> | |
| |<- cleaned_data --| | |
| |-- create_note(user, **data) ---->| |
| | | INSERT Note -|------------->|
| | | <-- Note pk -|-------------|
|<-- redirect /notes/<pk>--| | | |
End-to-end scenario: WebSocket Chat¶
Browser JS Nginx Uvicorn GroupChatConsumer Redis
| | | | |
|-- WS connect ----------> | | |
| (Cookie: sessionid=...) | | |
| |-- upgrade -> | |
| | |-- connect() -> |
| | | check_membership() |
| | | group_add(channel_name) -->|
| | | accept() + load_history() |
|<-- history JSON --------|-----------|<- send() ----| |
| | | | |
|-- send message --------> | | |
| {"content": "Hello"} |-- text --> | |
| | |-- receive() -> |
| | | save_message() → DB |
| | | group_send() ------------->|
| | | |
| | |<-- chat_message event -------|
|<-{"type":"message",...}-|-----------|<- send() ----| |
Common pitfalls¶
| Situation | Error | Solution |
|---|---|---|
| Lazy QuerySet from an async consumer | SynchronousOnlyOperation |
list() inside database_sync_to_async |
get_asgi_application() after importing notes_app |
AppRegistryNotReady |
reorder the imports in asgi.py |
TestCase for a consumer |
setUp objects disappear | TransactionTestCase |
Redis socket_timeout is not None |
TimeoutError on an idle WS |
"socket_timeout": None in CONFIG |
DebugExceptionMiddleware without if DEBUG: |
traceback in the HTTP response in prod | wrap it in if DEBUG: in settings.py |
note.group = group_instance; note.save() in a selector |
layer violation (mutation) | move it to services.py |