All source listed below is under MIT license if no LICENSE file stating different is available.

Rant Community - Developer Handover Documentation

Version: 1.0
Date: August 5, 2025

1. Introduction

Welcome to the Rant Community application. This document provides a comprehensive overview of the project's architecture, features, and implementation details. It is intended to facilitate a smooth handover to the new development team.

The Rant Community is a full-stack web application that allows users to post short text-based "rants," comment on them, vote, and interact with other users. It features a complete user authentication system, profile management, and a real-time notification system.

The application is built with a Python FastAPI backend, a dynamic frontend using both Jinja2 templates for server-side rendering (SSR) and a vanilla JavaScript component-based architecture for a single-page application (SPA) experience. Data persistence is handled by an SQLite database, accessed asynchronously.

2. Project Structure

The project is organized into the following key files and directories:

/
|-- main.py             # FastAPI application, API endpoints, SSR routes
|-- ads.py              # Asynchronous Database Set (SQLite wrapper)
|-- classic.html        # SPA-style frontend with JavaScript components
|-- locustfile.py       # Performance testing script for the API
|-- rant_community.db   # SQLite database file
|-- devrant_log.json    # Development log
|-- uploads/            # Directory for user-uploaded images
|-- static/             # Static assets (CSS, JS, images)
|   |-- index.html      # Duplicate of classic.html
|-- templates/          # Jinja2 templates for SSR
|   |-- base.html
|   |-- feed.html
|   |-- login.html
|   |-- notifications.html
|   |-- profile.html
|   |-- rant_detail.html
|   |-- search.html
|   |-- components/
|       |-- modals.html
|       |-- navigation.html
|       |-- rant_card.html

3. Backend (FastAPI)

The backend is a FastAPI application (main.py) responsible for serving the API and the server-side rendered pages.

3.1. API Endpoints

The application exposes a RESTful API for all core functionalities. All API endpoints are prefixed with /api.

Key Endpoints:

Users & Authentication:

  • POST /api/users: Register a new user.
  • POST /api/users/auth-token: Log in a user and receive an auth token.
  • GET /api/users/{user_id}: Fetch a user's profile.
  • POST /api/users/me/edit-profile: Edit the current user's profile.

Rants:

  • GET /api/rant/rants: Get a feed of rants.
  • POST /api/rant/rants: Create a new rant.
  • GET /api/rant/rants/{rant_id}: Get details of a specific rant.
  • POST /api/rant/rants/{rant_id}: Update a rant.
  • DELETE /api/rant/rants/{rant_id}: Delete a rant.

Comments, Votes, and Favorites:

  • POST /api/rant/rants/{rant_id}/comments: Add a comment to a rant.
  • POST /api/rant/rants/{rant_id}/vote: Vote on a rant.
  • POST /api/rant/rants/{rant_id}/favorite: Favorite a rant.
  • POST /api/rant/rants/{rant_id}/unfavorite: Unfavorite a rant.
  • POST /api/comments/{comment_id}/vote: Vote on a comment.

Notifications & Search:

  • GET /api/users/me/notif-feed: Get notifications for the current user.
  • GET /api/rant/search: Search for rants.

3.2. Authentication

Authentication is token-based. When a user logs in, a unique token is generated and stored in the auth_tokens table. This token is then sent to the client and must be included in the headers or body of subsequent requests to authenticated endpoints.

The authenticate_user function in main.py validates the provided token (token_id, token_key, user_id).

3.3. Database (ads.py)

The ads.py file contains the AsyncDataSet class, a powerful asynchronous wrapper for the SQLite database. It simplifies database operations by providing an intuitive, high-level API.

Key Features of AsyncDataSet:

  • Asynchronous Operations: All database calls are non-blocking, using aiosqlite.
  • Automatic Schema Migration: The class automatically adds missing tables and columns on the fly, preventing errors and simplifying development.
  • CRUD and More: Provides methods for insert, update, delete, get, find, upsert, count, and exists.
  • Raw SQL Execution: Allows for executing complex queries with execute_raw and query_raw.
  • Transactions: Supports atomic operations using an async with transaction context.
  • KV Store: Includes a simple key-value store functionality (kv_set, kv_get).

3.4. Database Schema

The database schema is defined in the init_db function in main.py. It consists of the following tables:

  • users: Stores user information, credentials, and profile details.
  • auth_tokens: Manages user authentication tokens.
  • rants: Contains all the rants posted by users.
  • comments: Stores comments on rants.
  • votes: Tracks user votes on rants and comments.
  • favorites: Manages users' favorited rants.
  • notifications: Stores notifications for users.

4. Frontend

The application employs a hybrid frontend strategy, combining server-side rendering (SSR) with a client-side single-page application (SPA) architecture.

4.1. Server-Side Rendering (SSR)

The main pages of the application (feed, rant details, profiles) are rendered on the server using Jinja2 templates. This approach ensures fast initial page loads and good SEO.

The templates/ directory contains all the Jinja2 templates. base.html serves as the main layout file. Reusable UI components are defined in templates/components/.

4.2. Single-Page Application (classic.html)

The classic.html file provides an alternative, fully client-side rendered version of the application. It is a self-contained SPA built with vanilla JavaScript, demonstrating a component-based architecture.

Key Components of the SPA:

  • EventBus: A global event bus for communication between different components. This decouples components and allows for a more modular architecture.
  • AuthManager: A singleton class that handles user authentication on the client side, including storing the auth token in localStorage.
  • Custom Elements (Web Components): The UI is built using custom elements for different parts of the application, such as:
    • rant-navigation
    • rant-card
    • feed-view
    • rant-detail-view
    • comments-section
    • profile-view
    • rant-modal
  • RantApp: The main application component that manages routing and view rendering.

5. Getting Started

5.1. Prerequisites

  • Python 3.7+
  • pip

5.2. Installation

  • Clone the repository.
  • Install the required Python packages: 
    pip install fastapi "uvicorn[standard]" aiosqlite python-multipart

5.3. Running the Application

Start the FastAPI server:

uvicorn main:app --host 0.0.0.0 --port 8111 --reload

The application will be available at http://127.0.0.1:8111.

5.4. Performance Testing

The project includes a locustfile.py for performance testing the API using Locust.

  • Install Locust: 
    pip install locust
  • Run the tests: 
    locust -f locustfile.py
  • Open http://localhost:8089 in your browser to start the test.

6. Key Features and Implementation

6.1. Rant and Comment System

Users can create, edit, and delete their own rants and comments. Content is sanitized using an escapeHtml function to prevent XSS attacks. Rants can have tags, which are stored as a JSON string in the database.

6.2. Voting System

Users can upvote (+1) or downvote (-1) rants and comments. The votes table tracks each vote to prevent users from voting multiple times on the same item. The score of rants, comments, and users is updated in real-time.

6.3. User Profiles

Each user has a public profile page displaying their rants, comments, and favorited posts. Users can edit their profile information, including their bio, skills, and social links.

6.4. Notifications

Users receive notifications for comments on their rants and for mentions. The navigation bar displays a real-time count of unread notifications. The /api/users/me/notif-feed endpoint marks notifications as read when they are fetched.

6.5. Search

The application provides a simple search functionality that looks for matching terms in rant text and tags.

7. Future Improvements

  • WebSocket Integration: Implement WebSockets for real-time updates (e.g., new comments, live notifications) without needing to reload the page.
  • Database Migration Tool: Integrate a proper database migration tool like Alembic to manage schema changes more robustly.
  • Frontend Framework: For more complex features, consider migrating the frontend to a modern JavaScript framework like React, Vue, or Svelte.
  • Containerization: Dockerize the application for easier deployment and environment consistency.
  • Testing: Expand the test suite with more comprehensive unit and integration tests for both the backend and frontend.
static
templates
.gitignore
ads.py
app.py
classic.html
locustfile.py
README.md