README.md

metadata

title: PoraHobeBot
emoji: 📚
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false

PoraHobeBot

Project Overview

PoraHobeBot is a web-based platform designed to facilitate the sharing and management of academic notes and resources. It provides a centralized repository for students to upload, browse, and categorize study materials, streamlining the exchange of knowledge. The application features a modern, responsive user interface and robust administrative tools for content moderation.

Features

User Features

• Authentication: Secure login and registration system supporting OAuth integration with Google and Discord.
• Note Management: Users can upload notes in various formats (files or external links).
• Resource Organization: Notes are categorized by subject and type (e.g., Lecture, Assignment, Reference) for easy retrieval.
• Search and Filter: Advanced filtering capabilities allow users to find specific resources quickly.
• Profile Management: Users can view their upload history and manage connected accounts.

Administrative Features

• Dashboard: A comprehensive overview of platform statistics, including total users, notes, and subjects.
• Content Moderation: Tools to review and delete inappropriate or irrelevant notes.
• Taxonomy Management: Administrators can create, edit, and remove subjects and note classifications.
• User Management: Capabilities to manage user roles and permissions.

Technical Architecture

The application is built using a monolithic architecture with server-side rendering.

• Backend: Python (Flask Framework)
• Database: SQLAlchemy ORM (SQLite for development, configurable for other RDBMS)
• Frontend: Jinja2 Templates, Tailwind CSS
• Storage: S3-compatible object storage for file persistence
• Authentication: Flask-Login, Flask-Dance (OAuth)

Installation and Setup

Prerequisites

• Python 3.13 or higher
• An S3-compatible storage service (e.g., AWS S3, MinIO, Cloudflare R2)
• Google and/or Discord Developer Application credentials (for OAuth support)

Step 1: Clone the Repository

git clone https://github.com/spreadsheets600/porahobebot.git
cd porahobebot

Step 2: Install Dependencies

It is recommended to use a virtual environment.

Using uv (recommended):

uv sync

Or using pip:

pip install -r requirements.txt

Note: If requirements.txt is missing, generate it from pyproject.toml or install dependencies manually as listed in the configuration.

Step 3: Configuration

Create a .env file in the project root directory. You can copy the structure from the provided configuration parameters.

# Core Security
SECRET_KEY=your_secure_random_key

# Database (for Hugging Face Spaces persistence)
DATABASE_URL=sqlite:////data/porahobebot.db

# Authentication (Optional if not using OAuth)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
DISCORD_BOT_TOKEN=your_discord_bot_token

# Storage (S3 Compatible)
S3_BUCKET_NAME=your_bucket_name
S3_ENDPOINT=your_s3_endpoint_url
S3_ACCESS_KEY_ID=your_access_key
S3_SECRET_KEY=your_secret_key

# Administration
ADMIN_SECRET_CODE=your_admin_secret_code

Step 4: Initialize the Database

Initialize the database schema and apply migrations.

flask db upgrade

Step 5: Seed Initial Data (Optional)

Populate the database with initial subjects or required data if a seed script is available.

python seed_subjects.py

Step 6: Run the Application

Start the development server.

python run.py

The application will be accessible at http://localhost:5000 (or the configured port).

Deployment

For production environments, it is recommended to use a production-grade WSGI server such as Gunicorn or uWSGI behind a reverse proxy like Nginx.

gunicorn -w 4 -b 0.0.0.0:8000 "app:create_app()"

Docker Setup

Build

docker build -t porahobebot:latest .

Run

docker run --rm -p 7860:7860 --env-file .env porahobebot:latest

App URL: http://localhost:7860

Deploy to Hugging Face Spaces (Docker)

1. Create a new Space on Hugging Face with:
   • SDK: Docker
2. In your Space repository, use README_SPACES.md content as README.md.
3. Add all runtime variables in Space Settings -> Variables and secrets (see .env.example).
4. Push this code to your Space:

pip install -U "huggingface_hub[cli]"
huggingface-cli login
git remote add space https://huggingface.co/spaces/<YOUR_USERNAME>/<YOUR_SPACE_NAME>
git push space main

License

[Insert License Information Here]

Contributing

Contributions are welcome. Please submit a pull request or open an issue for any enhancements or bug reports.