Notes Chat App Architecture¶
Components and responsibilities¶
| Component | File | Responsibility |
|---|---|---|
| Settings | notes_project/settings.py |
apps, DB, Channels, static, auth |
| Root URLs | notes_project/urls.py |
admin, accounts, app include |
| App URLs | notes_app/urls.py |
HTTP routes |
| WebSocket routing | notes_project/routing.py |
/ws/groups/<pk>/chat/ |
| Models | notes_app/models.py |
domain schema, constraints, indexes |
| Views | notes_app/views.py |
HTTP request/response, thin layer |
| Forms | notes_app/forms.py |
validation and Crispy layout |
| Selectors | notes_app/selectors.py |
read-only ORM queries, access scoping |
| Services | notes_app/services.py |
mutating operations (create/update/delete) |
| Consumer | notes_app/consumers.py |
WebSocket: GroupChatConsumer |
| Templates | templates/ + notes_app/templates/ |
HTML |
| Static | notes_app/static/notes_app/js/group_chat.js |
WebSocket JS client |
| Tests | notes_app/tests/ |
6 modules |
| ASGI | notes_project/asgi.py |
ProtocolTypeRouter |
Application layers¶
flowchart TD
Browser --> Nginx["Nginx :80"]
Nginx -->|HTTP| Uvicorn["Uvicorn :8001<br>ASGI server"]
Nginx -->|WebSocket| Uvicorn
Uvicorn --> ASGI["ProtocolTypeRouter<br>notes_project/asgi.py"]
ASGI -->|http| DjangoHTTP["Django HTTP stack<br>→ views.py"]
ASGI -->|websocket| AuthMW["AuthMiddlewareStack<br>→ routing.py"]
DjangoHTTP --> Views["views.py"]
Views --> Forms["forms.py"]
Views --> Selectors["selectors.py<br>(read)"]
Views --> Services["services.py<br>(write)"]
Selectors --> ORM["Django ORM"]
Services --> ORM
ORM --> PostgreSQL[("PostgreSQL<br>:5432")]
AuthMW --> Consumer["GroupChatConsumer<br>consumers.py"]
Consumer -->|database_sync_to_async| ORM
Consumer --> ChannelLayer["Channel Layer<br>Redis :6379"]
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,DjangoHTTP,Forms,Selectors,Services,ORM,AuthMW,Consumer step;
class ASGI decision;
class PostgreSQL,ChannelLayer success;
class Views warning;
ASGI and protocols¶
notes_project/asgi.py routes traffic by protocol type:
application = ProtocolTypeRouter({
"http": get_asgi_application(),
"websocket": AuthMiddlewareStack(
URLRouter(websocket_urlpatterns)
),
})
HTTP is handled by Django in the standard way.
WebSocket goes through AuthMiddlewareStack, which reads the session cookie and populates scope["user"].
WebSocket URL: /ws/groups/<group_pk>/chat/ → GroupChatConsumer.
Docker Compose¶
flowchart LR
db[("PostgreSQL<br>db:5432")]
redis[("Redis<br>redis:6379")]
web["web<br>uvicorn :8001"]
nginx["nginx<br>:80"]
ngrok[ngrok]
worker[celery-worker]
beat[celery-beat]
selenium["selenium<br>chrome"]
stests[selenium-tests]
db --> web
redis --> web
web --> nginx
nginx --> ngrok
db --> worker
redis --> worker
db --> beat
redis --> beat
selenium --> stests
nginx --> stests
classDef step fill:#eceff1,stroke:#546e7a,stroke-width:1px;
classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
class db,redis,ngrok,worker,beat,selenium,stests step;
class web,nginx success;
Dependencies: web, celery-worker and celery-beat start only after the db and redis health checks pass; selenium-tests (profile test) also waits for web, nginx and selenium.
The layering principle (Views → thin)¶
views.py ← HTTP coordination (thin layer)
↓ forms.py ← input data validation
↓ selectors.py ← read queries (returns a QuerySet or a list)
↓ services.py ← write operations (atomic transactions)
↓ models.py ← domain schema
Business logic is not added directly to a view without a documented reason.
Channel Layer¶
| Condition | Backend |
|---|---|
REDIS_URL is not set |
InMemoryChannelLayer (dev, single process) |
REDIS_URL is set |
RedisChannelLayer (Docker, production) |
socket_timeout=None in the RedisChannelLayer CONFIG is required — it prevents TimeoutError on idle WebSocket connections.