Istar

Istar is a Django web application for anonymous social posting, school timetable management. It includes a low-friction social feed, asynchronous voting, user bookmarks, and a timetable processing engine (tkb) that parses scheduling data from Chuyen Ha Tinh High School (Trường THPT Chuyên Hà Tĩnh, Vietnam).

---

Table of contents

1. Core architecture and applications
2. Key features
3. Database schema and relations
4. Tech stack and dependencies
5. Installation and local setup
6. Deployment configuration

---

Core architecture and applications

The project uses a modular Django application structure:

• Dtest/: The core project configuration directory containing routing (urls.py), ASGI/WSGI definitions, and settings (settings.py). The timezone is set to Asia/Ho_Chi_Minh.
• authenticate/: Handles user accounts, profile pages, and authentication security. It replaces the default Django admin registration, login, and password change templates, and includes a server-side paginated member portal.
• post/: Handles social posts. Implements CRUD operations for posts, asynchronous voting, and user bookmarks.
• tkb/ (Thời khóa biểu): Contains the timetable extractor. It uses backend parsers (TKBapi.py) to process and display real-time timetable updates based on school schedules.
• homepage/: Handles the landing page, routing, and general application descriptions.

---

Key features

User directory and authentication (authenticate)

• Account creation uses UserCreationForm without immediate email verification to simplify onboarding.
• The profile directory uses server-side pagination (django.core.paginator) limited to 10 profiles per page, displaying group indicators for administrators and staff.
• Public profiles display a feed of the user's posts, using optimized database subqueries (Coalesce and Subquery) to avoid performance bottlenecks.

Micro-blogging and voting (post)

• Upvotes and downvotes use AJAX fetch() requests to update post scores instantly without reloading the page.
• Client-side JavaScript measures the rendered height of long posts and appends a "See more..." toggle if the text overflows the layout bounds.
• Feeds can be filtered by time ranges (day, week, month) using timedelta constraints, sorted by a combination of upvote counts and post age.
• Users can save posts to a private bookmarks list, tracked via database annotations.

Timetable tracking (tkb)

• A backend script parses school schedule updates using requests and lxml.
• The parsed schedule dynamically updates user timetable grids to match changes at Chuyen Ha Tinh High School.

---

Database schema and relations

The application uses SQLite for development, extending Django's built-in contrib.auth.models.User model.

  +-------------------+              +-------------------+
  |     auth.User     | <----------+ |       Post        |
  +-------------------+              +-------------------+
    |               ^                  |               ^
    | id            | author           | id            | post
    v               |                  v               |
  +-------------------+              +-------------------+
  |       Vote        |              |     Bookmark      |
  +-------------------+              +-------------------+
  | user (FK)         |              | user (FK)         |
  | post (FK)         |              | post (FK)         |
  | voteType (Str)    |              | created_at (DT)   |
  +-------------------+              +-------------------+

Model constraints

1. Post:
   • title: A CharField limited to 255 characters.
   • body: A TextField for post content.
   • author: A foreign key to auth.User with models.CASCADE deletion.
   • date: An automatically populated DateTimeField (auto_now_add=True).
2. Vote:
   • Enforces a unique constraint via unique_together = ('user', 'post').
   • voteType: A choice field limited to up or down to prevent duplicate voting.
3. Bookmark:
   • Enforces a unique constraint via unique_together = ('user', 'post').
   • created_at: A DateTimeField tracking when the post was saved.

---

Tech stack and dependencies

The project relies on specific versions of the following packages:

Django==3.2.19             # Web framework core
pandas==2.3.2              # Data alignment for parsing timetables
numpy==2.3.2               # Numerical computing support
openpyxl==3.1.5            # Excel file parsing
lxml==6.0.1                # XML and HTML parsing
requests==2.32.5           # HTTP client for downloading schedules
gunicorn==23.0.0           # WSGI HTTP server for production
asgiref==3.6.0             # Async/sync compatibility layer
sqlparse==0.4.2            # SQL parsing and formatting

---

Installation and local setup

1. Set up a virtual environment

Ensure Python 3.8+ is installed. Clone the repository and initialize a virtual environment:

python3 -m venv venv

# Linux/macOS
source venv/bin/activate

# Windows CMD
venv\Scripts\activate.bat

2. Install dependencies

Install the required packages:

pip install --upgrade pip
pip install -r requirements.txt

3. Run database migrations

Set up the database schema:

python manage.py makemigrations
python manage.py migrate

4. Create an administrator account

Create a superuser to access the Django admin panel:

python manage.py createsuperuser

5. Start the development server

Run the local Django server:

python manage.py runserver

Open http://127.0.0.1:8000/ in a web browser.

---

Deployment configuration

Running with Gunicorn

To run the application via Gunicorn in a production environment:

gunicorn Dtest.wsgi:application --bind 0.0.0.0:8000 --workers 3

Collect static files

Compile static assets into a single directory before deployment:

python manage.py collectstatic --noinput

Assets are gathered into the staticfiles/ directory as specified in Dtest/settings.py.