Readflow

Readflow is a self‑hosted, feature‑rich feed reader built to consolidate web articles into a single, privacy‑first interface. From a developer’s standpoint it is an opinionated Go application that exposes both a GraphQL API and webhook endpoints for ingestion and egress. Its primary goal is to provide an extensible, offline‑ready reader that can be embedded in larger workflows or consumed by custom clients.

Technical Stack

• Language & Runtime: Go 1.22+; the codebase follows idiomatic Go patterns with a strong emphasis on concurrency safety and minimal runtime overhead.
• Web Framework: Uses the standard net/http package combined with the chi router for routing, and go-chi/httprate for rate‑limiting.
• Database: PostgreSQL is the sole persistence layer, accessed via pgx/sqlc. The schema supports articles, categories, users, and webhook configurations.
• Template Rendering: The UI is a modern SPA written in Svelte, served as static assets. A small Go HTTP handler delivers the PWA bundle.
• GraphQL: github.com/99designs/gqlgen powers the API, exposing queries for articles, categories, and webhook registration.
• Scripting Engine: Custom article transformations are driven by a sandboxed JavaScript engine (V8 or Otto), enabling per‑article processing rules.
• Containerization: A ready‑made Docker image (ncarlier/readflow) is published to Docker Hub. The docker-compose.yml mounts a sample passwd file and exposes the database via environment variables.

Core Capabilities

• Article Ingestion: Accepts raw URLs, PDFs, EPUBs, and ZIP archives. The ingestion pipeline normalizes content into a canonical HTML representation using go-readability and stores metadata (title, author, publish date).
• Offline Export: Articles can be exported in multiple formats (HTML, PDF, EPUB, ZIP). The export logic is pluggable through the scripting engine.
• Webhook Integration: Two sets of webhooks are available:
  • Incoming: Receive article payloads from external services (e.g., Pocket, Wallabag) via JSON POST requests.
  • Outgoing: Notify subscribers (e.g., newsletters, RSS feeds) when new articles appear.
• GraphQL API: Supports CRUD operations on articles, categories, and webhook subscriptions. Pagination is implemented via cursor‑based limits for efficient client queries.
• PWA Support: The UI is a fully responsive PWA, enabling offline browsing and push notifications through Service Workers.
• User Management: Basic authentication via a local passwd file or environment‑based credentials, with password hashing using Argon2.

Deployment & Infrastructure

Readflow is designed for lightweight, single‑node deployments but can be scaled horizontally with a PostgreSQL cluster. The Docker image exposes port 8080 and accepts the database URI via READFLOW_DATABASE_URI. For production, recommend:

• Persisting data volumes for PostgreSQL and user files.
• Using a reverse proxy (NGINX/Traefik) for TLS termination and HTTP/2.
• Leveraging Kubernetes or Docker Swarm to manage replicas; the stateless API can be load‑balanced, while a shared database ensures consistency.

Integration & Extensibility

• Plugin System: The scripting engine allows developers to inject custom JavaScript snippets that run during article ingestion or export.
• Webhooks: Expose RESTful endpoints for external services; the outgoing webhooks support arbitrary payloads and headers, making it trivial to integrate with newsletters or CI pipelines.
• GraphQL: Clients can build rich UIs that query only the fields they need, reducing over‑fetching.
• Configuration: TOML files expose fine‑grained settings (e.g., default export format, webhook retry strategy). The READFLOW_CONFIG environment variable can override values for CI/CD pipelines.

Developer Experience

• Documentation: Comprehensive docs at https://docs.readflow.app cover API usage, webhook configuration, and scripting examples.
• Community: The project is maintained by a small but active core team, with issue triage and feature requests handled promptly.
• Testing: The repository includes unit tests for core logic and integration tests for the GraphQL API, encouraging developers to contribute.
• Licensing: Apache‑2.0 license ensures freedom to modify, redistribute, and embed Readflow in proprietary systems without copyleft constraints.

Use Cases

Advantages Over Alternatives

• Zero Ads & Tracking: Full control over data, no third‑party analytics.
• Performance: Go’s compiled binaries and minimal dependencies yield fast startup times (~200