Feeds Fun

Feeds Fun is a self‑hosted news aggregator that blends automated tag generation, rule‑based scoring, and granular filtering into a single, extensible stack. At its core, the application consumes RSS/Atom feeds, enriches each entry with a set of tags—either from static rules or LLM‑driven processors—and surfaces the most relevant articles to users. The backend, written in Python and packaged as ffun on PyPI, exposes a RESTful API that powers a modern React‑based frontend (feeds-fun on NPM). Both components are tightly coupled through shared versioning, ensuring parity between UI and data contracts.

Technical Stack

• Backend: Python 3.10+, FastAPI framework, async I/O, and a lightweight dependency injection system. Persistence is handled by PostgreSQL via SQLAlchemy; Redis or another key‑value store can be plugged in for caching and session handling. The application is containerized with Docker Compose, providing separate services for the API, worker processes (tag processors), and optional authentication providers.
• Frontend: Vite‑powered React 18 project with TypeScript. State management is achieved through a custom hook layer that communicates with the backend over HTTPS using JWT or SuperTokens for multi‑user scenarios. Configuration is injected at build time via VITE_FFUN_* environment variables, allowing developers to override API endpoints, feature flags, or UI themes without modifying source code.
• Tag Processing: Feeds Fun ships with a pluggable “librarian” module that supports multiple processors—static domain tags, keyword extraction, and LLM‑based classifiers. Processor definitions are stored in TOML files (tag_processors.toml) and can be overridden by providing a custom path via FFUN_LIBRARIAN_TAG_PROCESSORS_CONFIG. The LLM layer (llms_framework) abstracts model interactions and can be configured with OpenAI, Gemini, or other providers through models.toml.

Core Capabilities

• Rule Engine: Users can define scoring rules that assign a numeric weight to tags. These scores are persisted in the database and drive the sorting algorithm exposed by /api/news/sorted.
• Filtering API: The backend accepts filter payloads (exclude_tags, include_tags) and returns paginated results, allowing client‑side applications to build sophisticated dashboards or custom feeds.
• Read Tracking: Each user’s read state is stored in a dedicated table, enabling “mark as read” actions and unread counters.
• Extensibility: New tag processors can be added by implementing the TagProcessor interface and registering it in the TOML configuration. Webhooks are supported for external services to subscribe to feed updates or scoring changes.

Deployment & Infrastructure

Feeds Fun is designed for production‑grade deployments. A single Docker Compose file can spin up a multi‑user instance with PostgreSQL, Redis, and the API/worker stack. For high availability, orchestrators like Kubernetes can run each service as a Deployment with StatefulSets for the database. The application exposes health endpoints (/healthz) and metrics (/metrics), making it straightforward to integrate with Prometheus or Grafana. Scaling is achieved by adding worker replicas for tag processing or horizontally scaling the API behind a load balancer; the stateless nature of the FastAPI server simplifies this process.

Integration & Extensibility

• Plugin System: The librarian’s processor registry allows developers to inject custom logic without touching the core codebase. This is ideal for organizations that need domain‑specific tagging or compliance rules.
• APIs & Webhooks: RESTful endpoints expose all CRUD operations for feeds, tags, and rules. Additionally, Feeds Fun can emit webhooks on significant events (e.g., new article fetched), enabling downstream automation such as Slack notifications or database mirroring.
• Customization: Frontend configuration via environment variables lets teams tailor the UI—enable/disable features, change color schemes, or point to a different API host—all without code changes.

Developer Experience

The project follows semantic versioning for both backend and frontend packages, ensuring that a given ffun release is always compatible with its corresponding feeds-fun UI. Documentation lives in the /docs directory and includes quick‑start guides for single‑user and multi‑user Docker setups, as well as detailed explanations of the tag processor configuration. Community support is active on GitHub Discussions and the project’s blog, where updates to the roadmap and new feature releases are announced. The open‑source license (MIT) removes barriers for commercial use, and the lightweight stack keeps resource footprints low.

Use Cases

• Enterprise News Hub: Companies can deploy Feeds Fun to curate internal and external feeds, applying policy‑based scoring to surface only approved content.
• Personal Knowledge Management: Developers or researchers can run a single‑user instance locally, leveraging LLM processors to tag niche topics and then filter for deep dives.
• Education Platforms: Academic institutions can expose curated feeds to students, with custom rules that prioritize peer‑reviewed sources.
• Data‑Driven Journalism: Media outlets can ingest competitor feeds, tag them automatically, and surface trends or gaps in coverage for editorial teams.

Advantages

Feeds Fun offers a balance of out‑of‑the‑box functionality and deep customizability. Its lightweight Python/React stack delivers high performance while keeping the codebase approachable for contributors. The pluggable tag processors and rule engine give developers fine‑grained control over content relevance, a feature rarely found in other