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.
@@ -0,0 +1,112 @@
+# Discord Clone
+
+* `uv` jako główne narzędzie do zarządzania pakietami i wirtualnymi środowiskami
+* workdir przygotowany przy użyciu `uv init .` i `uv venv`
+
+---
+
+### Cel zadania
+Stworzenie webowej aplikacji komunikacyjnej inspirowanej platformą Discord. Aplikacja umożliwia komunikację w czasie rzeczywistym, zarządzanie rolami i uprawnieniami oraz udostępnia interfejs responsywny.
+
+### Wymagania funkcjonalne
+1. **System użytkowników**  
+   - Rejestracja (login, email, hasło)  
+   - Logowanie i wylogowanie  
+   - Walidacja (unikalny login i email, siła hasła)  
+   - Edycja profilu (awatar, opis)
+
+2. **Role i uprawnienia** (minimum 3 role)  
+   - *Administrator* – pełny dostęp, zarządzanie użytkownikami i kanałami  
+   - *Moderator* – zarządzanie wiadomościami, blokowanie użytkowników  
+   - *Użytkownik* – wysyłanie wiadomości, korzystanie z kanałów  
+   - Dynamiczne przypisywanie ról, egzekwowanie uprawnień w backendzie
+
+3. **Komunikacja**  
+   - Kanały publiczne/grupowe: tworzenie, dołączanie, historia wiadomości  
+   - Wiadomości prywatne (DM) między dwoma użytkownikami  
+   - Obsługa czasu rzeczywistego (WebSocket, np. Django Channels + Redis)
+
+4. **Multimedia**  
+   - Wiadomości tekstowe, obrazy, nagrania audio (pliki dźwiękowe)
+
+5. **Moderacja**  
+   - Blokowanie użytkowników, usuwanie wiadomości  
+   - (Opcjonalnie) zgłaszanie wiadomości/użytkowników
+
+6. **Funkcje dodatkowe (mile widziane)**  
+   - Status online/offline, powiadomienia o nowych wiadomościach  
+   - Wyszukiwanie użytkowników/kanałów, emoji/reakcje
+
+### Frontend
+- Interfejs inspirowany Discordem (responsywny)
+- Wykorzystanie frameworka Bootstrap
+- Estetyczne formularze logowania i rejestracji (gotowe szablony CSS)
+- Obsługa WebSocket po stronie klienta (np. JavaScript)
+
+### Backend
+- Framework: **Django** (zalecane rozszerzenia: Django REST Framework, Django Channels)
+- WebSocket do komunikacji w czasie rzeczywistym (np. z użyciem Redis jako warstwy kanałów)
+- Obsługa przesyłania plików (obrazy, audio)
+- Własna strona błędu 404 i 500
+
+### Środowisko uruchomieniowe – **kontenery Docker**
+Aplikacja nie wymaga hostowania na zewnętrznych platformach. Całość musi być gotowa do uruchomienia w kontenerach za pomocą **Docker** i **Docker Compose**.
+
+Pliki wymagane w repozytorium:
+- `Dockerfile` – budujący obraz aplikacji Django (wraz z zależnościami, np. z pliku `requirements.txt`)
+- `docker-compose.yml` – definiujący wszystkie usługi niezbędne do działania systemu, co najmniej:
+  - `web` – serwer Django (z obsługą ASGI np. Daphne/Uvicorn dla WebSocket)
+  - `db` – baza danych PostgreSQL
+  - `redis` – serwer Redis (dla Django Channels)
+- Plik `.env` lub komentarze w `docker-compose.yml` wskazujące, jak skonfigurować zmienne środowiskowe (np. `SECRET_KEY`, dane dostępowe do bazy)
+
+Uruchomienie aplikacji sprowadza się do:
+```bash
+docker-compose up --build
+```
+Po starcie wszystkie migracje powinny zostać wykonane automatycznie, a aplikacja dostępna pod `http://localhost:8000`.
+
+### Sposób oddania pracy
+- Repozytorium kodu (np. GitHub, GitLab) zawierające cały projekt, w tym `Dockerfile`, `docker-compose.yml` oraz instrukcję uruchomienia (`README.md` z komendą `docker-compose up`).
+- Link do repozytorium umieszczony w pliku `.txt` na platformie Moodle.
+- Nie jest wymagane żadne publiczne wdrożenie – oceniana będzie poprawność działania lokalnego po wykonaniu `docker-compose up`.
+
+---
+
+## 🚀 Jak uruchomić projekt
+
+1. **Wymagania**: Upewnij się, że masz zainstalowane **Docker** oraz **Docker Compose**.
+2. **Uruchomienie aplikacji**:
+   Otwórz terminal w głównym katalogu projektu i uruchom:
+   ```bash
+   docker-compose up --build
+   ```
+3. **Automatyczna inicjalizacja**:
+   - Uruchomi się baza danych PostgreSQL, serwer Redis oraz serwer webowy Daphne.
+   - Migracje bazy danych zostaną wygenerowane i zaaplikowane automatycznie.
+   - Domyślne konto **Administratora** zostanie stworzone.
+4. **Dostęp do aplikacji**:
+   Otwórz przeglądarkę i wejdź na: [http://localhost:8000](http://localhost:8000)
+
+## 👑 Przewodnik dla Administratora
+
+**Domyślne dane logowania (Administrator):**
+- **Login**: `admin`
+- **Hasło**: `admin`
+
+**Funkcje i uprawnienia:**
+- **Panel Administracyjny**: Dostępny z paska nawigacji po zalogowaniu. Pozwala na przegląd użytkowników, zmianę ról (Administrator, Moderator, Użytkownik) oraz globalne blokowanie/odblokowywanie.
+- **Hierarchia ról**: 
+  - **Administrator** ma pełny dostęp do wszystkich kanałów, może usuwać dowolne wiadomości i kanały, a także zarządzać rolami.
+  - **Moderator** może usuwać nieodpowiednie wiadomości i blokować użytkowników, ale nie może zmieniać ról.
+  - **Użytkownik** może tworzyć kanały, pisać w nich, wysyłać wiadomości prywatne i usuwać własne wiadomości.
+
+## ✅ Zgodność z wymaganiami
+
+Projekt w pełni realizuje założenia:
+1. **System użytkowników**: Wbudowana rejestracja, logowanie, walidacja unikalności oraz panel edycji profilu (awatar, opis).
+2. **Role i uprawnienia**: Działają 3 wymagane role (Admin, Moderator, Użytkownik). Backend skutecznie weryfikuje uprawnienia.
+3. **Komunikacja w czasie rzeczywistym**: Wiadomości w kanałach publicznych oraz DM opierają się na technologii WebSockets (Django Channels + Redis).
+4. **Multimedia**: Dodano obsługę przesyłania plików, które od razu po przesłaniu wyświetlają się innym użytkownikom jako obrazy lub odtwarzacze audio.
+5. **Moderacja**: Administrator/Moderator może usuwać niepożądane wiadomości oraz całkowicie blokować dostęp wybranym użytkownikom.
+6. **Środowisko Docker**: Całość działa w odseparowanych kontenerach (web, db, redis) uruchamianych jednym poleceniem, z automatycznymi migracjami i początkowym seedowaniem bazy.