balanceboard/README.md

BalanceBoard

A Reddit-style content aggregator that collects posts from multiple platforms (Reddit, Hacker News, RSS feeds) and presents them in a unified, customizable feed.

Features

• Multi-Platform Support: Collect content from Reddit, Hacker News, and RSS feeds
• Automated Polling: Background service polls sources at configurable intervals
• User Authentication: Local accounts with bcrypt password hashing and Auth0 OAuth support
• Anonymous Browsing: Browse public feed without creating an account
• Password Reset: Secure token-based password reset mechanism
• Customizable Feeds: Filter and customize content based on your preferences
• Admin Panel: Manage polling sources, view logs, and configure the system
• Modern UI: Card-based interface with clean, responsive design

Quick Start

Prerequisites

• Python 3.12+
• PostgreSQL database
• Docker (for containerized deployment)

Local Development

1. Clone the repository

   git clone https://git.scorpi.us/chelsea/balanceboard.git
   cd balanceboard
   

2. Set up environment

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

3. Configure environment variables

   cp .env.example .env
   # Edit .env with your database credentials and settings
   

4. Initialize the database

   python3 -c "from app import create_app; from database import db; app = create_app(); app.app_context().push(); db.create_all()"
   

5. Run migrations (if needed)

   python3 migrate_password_reset.py
   

6. Start the application

   python3 app.py
   

7. Access the application

   • Open browser to http://localhost:5021
   • Create an account or browse anonymously

Docker Deployment

The included docker-compose.yml runs the app plus a PostgreSQL database, with persistent volumes for the database, collected posts, and backups.

1. Configure environment

   cp .env.example .env
   # Edit .env — at minimum set SECRET_KEY to a long random string
   

2. Build and start the stack

   docker compose up -d --build
   

3. Access the application

   • Open browser to http://localhost:5021
   • Create an account or browse anonymously

Useful commands:

docker compose logs -f app     # follow app logs
docker compose down             # stop the stack (keeps data volumes)
docker compose down -v          # stop and delete all data volumes

To publish the image to the registry instead of building locally:

docker build -t git.scorpi.us/chelsea/balanceboard:latest .
docker push git.scorpi.us/chelsea/balanceboard:latest

See DEPLOYMENT.md for detailed deployment instructions.

Configuration

Platform Sources

Configure available platforms and communities in platform_config.json:

{
  "reddit": {
    "name": "Reddit",
    "communities": [
      {
        "id": "programming",
        "name": "r/programming",
        "description": "Computer programming"
      }
    ]
  }
}

Polling Configuration

Admins can configure polling sources via the Admin Panel:

• Platform: reddit, hackernews, or rss
• Source ID: Subreddit name, or RSS feed URL
• Poll Interval: How often to check for new content (in minutes)
• Max Posts: Maximum posts to collect per poll
• Fetch Comments: Whether to collect comments
• Priority: low, medium, or high

Environment Variables

Key environment variables (see .env.example):

• DATABASE_URL: PostgreSQL connection string
• SECRET_KEY: Flask secret key for sessions
• AUTH0_DOMAIN: Auth0 domain (if using OAuth)
• AUTH0_CLIENT_ID: Auth0 client ID
• AUTH0_CLIENT_SECRET: Auth0 client secret

Architecture

Components

• Flask Web Server (app.py): Main application server
• Polling Service (polling_service.py): Background scheduler for data collection
• Data Collection (data_collection.py, data_collection_lib.py): Platform-specific data fetchers
• Database Models (models.py): SQLAlchemy ORM models
• User Service (user_service.py): User authentication and management

Database Schema

• users: User accounts with authentication
• poll_sources: Configured polling sources
• poll_logs: History of polling activities
• user_sessions: Active user sessions

Data Flow

1. Polling service checks enabled sources at configured intervals
2. Data collection fetchers retrieve posts from platforms
3. Posts are normalized to a common schema and stored in data/posts/
4. Web interface displays posts from the feed
5. Users can filter, customize, and interact with content

API Endpoints

Public Routes

• GET /: Main feed (anonymous or authenticated)
• GET /login: Login page
• POST /login: Authenticate user
• GET /register: Registration page
• POST /register: Create new account
• GET /password-reset-request: Request password reset
• POST /password-reset-request: Send reset link
• GET /password-reset/<token>: Reset password form
• POST /password-reset/<token>: Update password

Authenticated Routes

• GET /settings: User settings
• GET /logout: Log out

Admin Routes

• GET /admin: Admin panel
• GET /admin/polling: Manage polling sources
• POST /admin/polling/add: Add new source
• POST /admin/polling/update: Update source settings
• POST /admin/polling/poll: Manually trigger poll

Development

Project Structure

balanceboard/
├── app.py                      # Main Flask application
├── polling_service.py          # Background polling service
├── data_collection.py          # Data collection orchestration
├── data_collection_lib.py      # Platform-specific fetchers
├── models.py                   # Database models
├── user_service.py             # User management
├── database.py                 # Database setup
├── platform_config.json        # Platform configurations
├── filtersets.json             # Content filter definitions
├── templates/                  # Jinja2 templates
├── static/                     # Static assets (CSS, JS)
├── themes/                     # UI themes
├── data/                       # Data storage
│   ├── posts/                  # Collected posts
│   ├── comments/               # Collected comments
│   └── moderation/             # Moderation data
├── requirements.txt            # Python dependencies
├── Dockerfile                  # Docker image definition
├── docker-compose.yml          # Docker composition
├── README.md                   # This file
└── DEPLOYMENT.md               # Deployment instructions

Adding a New Platform

1. Add platform config to platform_config.json
2. Implement fetcher in data_collection_lib.py:
   • fetchers.getPlatformData()
   • converters.platform_to_schema()
   • builders.build_platform_url()
3. Update routing in getData() function
4. Test data collection
5. Add to available sources in admin panel

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

See DEPLOYMENT.md for commit and issue management guidelines.

License

This is a personal project by Chelsea. All rights reserved.

Support

For issues and feature requests, please use the issue tracker at: https://git.scorpi.us/chelsea/balanceboard/issues