# Fedi Feed Router (FFR) v1.0.0

<div align="center">
<img src="backend/public/images/ffr-logo-600.png" alt="FFR Logo" width="200">

**A minimal working version — limited to two hardcoded sources, designed for self-hosters.**  
*Future versions will expand configurability and support.*
</div>

---

## 🔰 Project Overview

**One-liner:** FFR routes content from RSS/Atom feeds to the fediverse based on keyword matching.

FFR is a self-hosted tool that monitors RSS/Atom feeds, filters articles based on keywords, and automatically publishes matching content to fediverse platforms like Lemmy. This v1.0.0 release provides a working foundation with two hardcoded news sources (CBC and BBC), designed specifically for self-hosters who want a simple, privacy-first solution without SaaS dependencies.

## ⚙️ Features

Current v1.0.0 features:
- ✅ Fetches articles from two hardcoded RSS feeds (CBC News, BBC News)
- ✅ Keyword-based content filtering and matching
- ✅ Automatic posting to Lemmy communities
- ✅ Web dashboard for monitoring and management
- ✅ Docker-based deployment for easy self-hosting
- ✅ Privacy-first design with no external dependencies

Limitations (to be addressed in future versions):
- Feed sources are currently hardcoded (not user-configurable)
- Only supports Lemmy as target platform
- Basic keyword matching (no regex or complex rules yet)

## 🚀 Installation

### Quick Start with Docker

1. **Clone the repository:**
   ```bash
   git clone https://codeberg.org/lvl0/ffr.git
   cd ffr
   ```

2. **Create environment file:**
   ```bash
   cp docker/production/.env.example .env
   ```

3. **Configure your environment variables:**
   ```env
   # Required variables only
   APP_URL=http://your-domain.com:8000
   DB_PASSWORD=your-secure-db-password
   DB_ROOT_PASSWORD=your-secure-root-password
   ```

4. **Start the application:**
   ```bash
   docker-compose -f docker/production/docker-compose.yml up -d
   ```

The application will be available at `http://localhost:8000`

### System Requirements

- Docker and Docker Compose (or Podman)
- 2GB RAM minimum
- 10GB disk space
- Linux/macOS/Windows with WSL2

## 🕹️ Usage

### Web Interface

Access the dashboard at `http://localhost:8000` to:
- View fetched articles
- Monitor posting queue
- Check system logs
- Manage keywords (coming in v2.0)

### Manual Commands

Trigger article refresh manually:
```bash
docker compose exec app php artisan article:refresh
```

View application logs:
```bash
docker compose logs -f app
```

### Scheduled Tasks

The application automatically:
- Fetches new articles every hour
- Publishes matching articles every 5 minutes
- Syncs with Lemmy communities every 10 minutes

## 📜 Logging & Debugging

**Log locations:**
- Application logs: Available in web dashboard under "Logs" section
- Docker logs: `docker compose logs -f app`
- Laravel logs: Inside container at `/var/www/html/backend/storage/logs/`

**Debug mode:**
To enable debug mode for troubleshooting, add to your `.env`:
```env
APP_DEBUG=true
```
⚠️ Remember to disable debug mode in production!

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. **Report bugs:** Open an issue describing the problem
2. **Suggest features:** Create an issue with your idea
3. **Submit PRs:** Fork, create a feature branch, and submit a pull request
4. **Improve docs:** Documentation improvements are always appreciated

For development setup, see the [Development Setup](#development-setup) section below.

## 📘 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).  
See [LICENSE](LICENSE) file for details.

## 🧭 Roadmap

### v1.0.0 (Current Release)
- ✅ Basic feed fetching from hardcoded sources
- ✅ Keyword filtering
- ✅ Lemmy posting
- ✅ Web dashboard
- ✅ Docker deployment

### v2.0.0 (Planned)
- [ ] User-configurable feed sources
- [ ] Advanced filtering rules (regex, boolean logic)
- [ ] Support for Mastodon and other ActivityPub platforms
- [ ] API for external integrations
- [ ] Multi-user support with permissions

### v3.0.0 (Future)
- [ ] Machine learning-based content categorization
- [ ] Feed discovery and recommendations
- [ ] Scheduled posting with optimal timing
- [ ] Analytics and insights dashboard

---

## Development Setup

For contributors and developers who want to work on FFR:

### Prerequisites

- Podman and podman-compose (or Docker)
- Git
- PHP 8.2+ (for local development)
- Node.js 18+ (for frontend development)

### Quick Start

1. **Clone and start the development environment:**
   ```bash
   git clone https://codeberg.org/lvl0/ffr.git
   cd ffr
   ./docker/dev/podman/start-dev.sh
   ```

2. **Access the development environment:**
   - Web interface: http://localhost:8000
   - Vite dev server: http://localhost:5173
   - Database: localhost:3307
   - Redis: localhost:6380

### Development Commands

```bash
# Run tests with coverage
podman-compose -f docker/dev/podman/docker-compose.yml exec app bash -c "cd backend && XDEBUG_MODE=coverage php artisan test --coverage-html=coverage-report"

# Execute artisan commands
podman-compose -f docker/dev/podman/docker-compose.yml exec app php artisan migrate
podman-compose -f docker/dev/podman/docker-compose.yml exec app php artisan tinker

# View logs
podman-compose -f docker/dev/podman/docker-compose.yml logs -f

# Access container shell
podman-compose -f docker/dev/podman/docker-compose.yml exec app bash

# Stop environment
podman-compose -f docker/dev/podman/docker-compose.yml down
```

### Development Features

- **Hot reload:** Vite automatically reloads frontend changes
- **Pre-seeded database:** Sample data for immediate testing
- **Laravel Horizon:** Queue monitoring dashboard
- **Xdebug:** Configured for debugging and code coverage
- **Redis:** For caching, sessions, and queues

---

## Support

For help and support:
- 💬 Open a [Discussion](https://codeberg.org/lvl0/ffr/discussions)
- 🐛 Report [Issues](https://codeberg.org/lvl0/ffr/issues)

---

<div align="center">
Built with ❤️ for the self-hosting community
</div>