Update.

Browse Source
This commit is contained in:
retoor 2025-08-05 03:59:28 +02:00
parent d1394506ab
commit 9e99ad8b42
1 changed files with 199 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
README.md Normal file
View File

@ -0,0 +1,199 @@
# 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.