Blogistan 📝

Blogistan is a full-featured blogging platform that enables users to view, create, and manage blog posts. It integrates a rich-text editor for publishing and features an asynchronous, interactive commenting and reply system.

---

Warning

Legacy Django Version & Compatibility Warning

This codebase was created and structured using Django 3.2.5 (an LTS version that reached End of Life in April 2024).

• Python Version Recommendation: It is highly recommended to run this project using Python 3.8 to 3.10. Newer versions (e.g. Python 3.11+) may trigger deprecation warnings or import compatibility issues with legacy packages (like the older version of djangorestframework or deprecated library functions used in Django 3.2).
• Dependency Management: Ensure you pin package installations to compatible ranges (e.g. django>=3.2,<4.0 and djangorestframework>=3.12,<3.14).

---

🛠️ Architecture & Project Structure

The project has a unified Django codebase split conceptually into a backend API/Admin layer and a frontend rendering layer:

Blogistan/
├── blog/                  # Main application containing views, models, forms, static, and templates
│   ├── static/            # Frontend static assets (CSS, images)
│   ├── templates/         # Frontend server-side rendered Django templates
│   ├── admin.py           # Admin panel model registrations (includes Summernote WYSIWYG)
│   ├── forms.py           # Forms mapping models to UI fields
│   ├── models.py          # SQLite database schema models
│   ├── serializers.py     # Django Rest Framework serializers for REST APIs
│   ├── urls.py            # Routing endpoints for templates and REST APIs
│   └── views.py           # Controller logic (views & API controllers)
├── Blogistan/             # Core project configuration
│   ├── settings.py        # Django application configurations (Django 3.2.5 configuration)
│   └── urls.py            # Global URL routing entrypoint
├── django_summernote/     # Bundled local version of the Summernote rich text editor app
├── manage.py              # Django execution script
└── blog.sqlite3           # Local SQLite database (pre-configured)

🖥️ Frontend vs. ⚙️ Backend Responsibilities

1. The Backend

• Django Application (blog): Handles routing, custom forms (forms.py), database models (models.py), and controllers (views.py).
• REST APIs: Powered by Django Rest Framework (DRF) in views.py and serialized using serializers.py. These serve API responses for interactive commenting features.
• Rich Text Editing (django_summernote): Locally bundled WYSIWYG editor integration, allowing administrators to format blog content via the admin panel.

2. The Frontend

• Server-Side Rendered (SSR) Templates: Located in templates/. It uses Django templates layout inheritance starting from layout.html.
• Asynchronous Client-Side Scripts: Inline JavaScript embedded in blog_post.html and comment.html handles live comment/reply loading and submissions via browser fetch() APIs and custom CSRF token validation.
• Styles: Pre-compiled minified styles are stored in style.min.css.

---

📊 Database Schema

Below is the relationship diagram showing how Django's authentication model is extended and connected to Blogistan objects:

      ┌─────────────────────────┐
      │   django.contrib.User   │ ◄─────────────────────────┐
      ├─────────────────────────┤                           │
      │ id (PK)                 │                           │
      │ username                │                           │
      │ email                   │                           │
      │ password                │                           │
      └────────────┬────────────┘                           │
                   │ (1:1 Extension)                        │
                   ▼                                        │
      ┌─────────────────────────┐                           │
      │         Author          │                           │
      ├─────────────────────────┤                           │
      │ user_ptr_id (PK, FK)    │                           │
      │ desc                    │                           │
      │ image                   │                           │
      └────────────┬────────────┘                           │
                   │ (1:N Publishes)                        │
                   ▼                                        │
      ┌─────────────────────────┐                           │
      │        BlogPost         │                           │
      ├─────────────────────────┤                           │
      │ id (PK)                 │                           │
      │ title                   │                           │
      │ urlpattern              │                           │
      │ content_html            │                           │
      │ date_added              │                           │
      │ author_id (FK)          │                           │
      └────────────┬────────────┘                           │
                   │ (1:N Has)                              │
                   ▼                                        │ (Writes Comment/Reply)
      ┌─────────────────────────┐                           │
      │     BlogPostComment     │ ──(user_id: FK)───────────┼─┘
      ├─────────────────────────┤                           │
      │ id (PK)                 │                           │
      │ blog_post_id (FK)       │                           │
      │ user_id (FK)            │                           │
      │ body                    │                           │
      │ time_added              │                           │
      └────────────┬────────────┘                           │
                   │ (1:N Has)                              │
                   ▼                                        │
      ┌─────────────────────────┐                           │
      │  BlogPostCommentReply   │ ──(user_id: FK)───────────┘
      ├─────────────────────────┤
      │ id (PK)                 │
      │ comment_id (FK)         │
      │ user_id (FK)            │
      │ body                    │
      │ time_added              │
      └─────────────────────────┘

---

🔗 API Reference

All interactive comments and reply endpoints are structured as REST APIs.

Endpoint	Method	Description
/blog/api/list-comments/<int:id>	GET	Retrieves list of comments for blog post id
/blog/api/create-comment/	POST	Creates a new comment on a blog post
/blog/api/list-replies/<int:id>	GET	Retrieves list of replies for comment id
/blog/api/create-reply/	POST	Creates a new reply to a comment
/blog/api/user-detail/<int:id>	GET	Retrieves basic user information (username, first name, last name)

---

🚀 Setup & Installation Guide

Follow these steps to set up and run Blogistan locally:

Prerequisites

• Python: 3.8, 3.9, or 3.10 (recommended for Django 3.2 compatibility)
• Virtual Environment Tool: venv or virtualenv

Steps

1. Clone the Repository

   git clone <repository-url>
   cd Blogistan

2. Create and Activate a Virtual Environment

   python3 -m venv env
   source env/bin/activate

3. Install Dependencies Install the correct legacy version range requirements:

   pip install "django>=3.2.0,<4.0.0" "djangorestframework>=3.12.0,<3.14.0" python-dotenv pillow

   Note: pillow is required for handling Author image uploads, and python-dotenv loads key credentials.

4. Configure the Environment Create a .env file in the root workspace folder:

   DJANGO_SECRET_KEY=your_secure_random_key_here

5. Run Database Migrations Apply migrations to build the SQLite tables locally:

   python manage.py migrate

6. Create a Superuser Create an administrative user to log in and publish posts:

   python manage.py createsuperuser

7. Start the Development Server

   python manage.py runserver

   • Access the frontend at: http://127.0.0.1:8000
   • Access the django administration panel at: http://127.0.0.1:8000/admin

---

📝 Usage Instructions

Creating Blog Posts

1. Start the server and navigate to /admin.
2. Login with your superuser credentials.
3. Add a new Author (associating it with your user account, upload an image and add a description).
4. Add a new Blog Post. The WYSIWYG editor allows rich text styling, headers, and media. Add a title, matching slug (URL Pattern), and assign the post to the Author.
5. Save the post. It will now be featured on the homepage!

Managing Comments & Replies

Users logged into the application can submit comments on the detailed blog posts views, and add replies to other comments. All list updates happen asynchronously via vanilla JavaScript requests.