docs: add README and architecture overview

2026-04-28 12:36:50 +02:00
parent be661161eb
commit aba0972582
2 changed files with 165 additions and 0 deletions
@@ -0,0 +1,53 @@
+# Project Architecture
+
+Below is a 3-layer architectural diagram illustrating how the Discord Clone Proof-of-Concept is built and how it operates, especially after consolidating the real-time layer into PostgreSQL.
+
+```mermaid
+graph TD
+    %% Styling
+    classDef client fill:#e1f5fe,stroke:#0288d1,stroke-width:2px;
+    classDef backend fill:#e8f5e9,stroke:#388e3c,stroke-width:2px;
+    classDef data fill:#fff3e0,stroke:#f57c00,stroke-width:2px;
+    
+    subgraph Layer 1: Client/Frontend Layer
+        B[Web Browser]:::client
+        JS[JavaScript / WebSockets]:::client
+        UI[Bootstrap UI / HTML5]:::client
+        
+        B -->|Renders| UI
+        B -->|Executes| JS
+    end
+
+    subgraph Layer 2: Application/Backend Layer
+        Daphne[Daphne ASGI Server]:::backend
+        Django[Django Framework]:::backend
+        Channels[Django Channels]:::backend
+        
+        JS <-->|WSS/WS connection| Daphne
+        B <-->|HTTP GET/POST| Daphne
+        
+        Daphne -->|HTTP Routing| Django
+        Daphne -->|WebSocket Routing| Channels
+    end
+
+    subgraph Layer 3: Data Layer
+        DB[(PostgreSQL Database)]:::data
+        
+        %% Combined database logic
+        Django <-->|ORM Queries / Migrations| DB
+        Channels <-->|LISTEN/NOTIFY / Publish-Subscribe| DB
+    end
+    
+    class B,JS,UI client;
+    class Daphne,Django,Channels backend;
+    class DB data;
+```
+
+### Layer Details
+
+1. **Client / Frontend Layer**: 
+   The user interacts with the standard HTML/CSS generated by Django templates, styled with Bootstrap. A lightweight JavaScript script establishes a continuous WebSocket connection to the server for receiving real-time events (like new messages or files).
+2. **Application / Backend Layer**: 
+   The entire application is served by **Daphne**, an ASGI server. Daphne intelligently routes standard HTTP traffic (like form submissions or page loads) to **Django's** synchronous views, and routes persistent WebSocket connections to **Django Channels** async consumers.
+3. **Data Layer**: 
+   Instead of using multiple stores (e.g., PostgreSQL for data and Redis for pub/sub), the project uses a unified **PostgreSQL** database. Standard Django queries handle users and messages, while the `channels_postgres` plugin utilizes Postgres's native `LISTEN/NOTIFY` capabilities to broadcast real-time events to connected clients.