django-discord/ARCHITECTURE.md

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.

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.