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**
   ```bash
   git clone https://git.scorpi.us/chelsea/balanceboard.git
   cd balanceboard
   ```

2. **Set up environment**
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   ```

3. **Configure environment variables**
   ```bash
   cp .env.example .env
   # Edit .env with your database credentials and settings
   ```

4. **Initialize the database**
   ```bash
   python3 -c "from app import app, db; app.app_context().push(); db.create_all()"
   ```

5. **Run migrations (if needed)**
   ```bash
   python3 migrate_password_reset.py
   ```

6. **Start the application**
   ```bash
   python3 app.py
   ```

7. **Access the application**
   - Open browser to `http://localhost:5000`
   - Create an account or browse anonymously

### Docker Deployment

1. **Build the image**
   ```bash
   docker build -t git.scorpi.us/chelsea/balanceboard:latest .
   ```

2. **Push to registry**
   ```bash
   docker push git.scorpi.us/chelsea/balanceboard:latest
   ```

3. **Deploy with docker-compose**
   ```bash
   docker-compose up -d
   ```

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions.

## Configuration

### Platform Sources

Configure available platforms and communities in `platform_config.json`:

```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](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