Add comprehensive README documentation
Created README.md with complete project documentation: - Project overview and feature list - Quick start guide for local development - Docker deployment instructions - Configuration details for platforms and polling - Architecture overview and data flow - API endpoint documentation - Project structure and file organization - Guide for adding new platforms - Contributing guidelines 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
229
README.md
Normal file
229
README.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user