diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..841a3df --- /dev/null +++ b/ARCHITECTURE.md @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..07d0385 --- /dev/null +++ b/README.md @@ -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. \ No newline at end of file