From f22069473581430eb6e08bceea3a4a0c0c9c67d3 Mon Sep 17 00:00:00 2001 From: chelsea Date: Sat, 11 Oct 2025 19:02:47 -0500 Subject: [PATCH] Add comprehensive README documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 229 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..7746891 --- /dev/null +++ b/README.md @@ -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/`: Reset password form +- `POST /password-reset/`: 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