Broken Cloud News is a cloud-security briefing platform with a central control plane, a split persistence layer, and deployable processing services that can run either in-process or behind internal HTTP endpoints.

It collects security signals from GHSA, RSS, Reddit, and Twitter/X, analyzes and ranks them, generates briefings and newsletters, evaluates draft quality, distributes approved output, and stores evaluation and review data for replay and benchmarking.

What It Does

• collects and normalizes security signals from GHSA, RSS, Reddit, and Twitter/X
• analyzes, scores, and canonicalizes items before generation
• generates daily briefings and monthly newsletters with critic/verifier loops
• distributes approved output to Telegram, Discord, Ghost, Substack, and email
• stores generation, review, distribution, and evaluation data for replay, shadowing, and benchmarking
• exposes workflow queue backlog, lane health, and failed-job drill-downs in the dashboard

Documentation

• ARCHITECTURE.md: system model, deployable services, persistence boundaries, and diagrams
• docs/operations.md: setup, Compose topology, environment variables, networking, and deployment notes
• docs/cli.md: CLI command reference, evaluation lanes, queue controls, and operator/admin commands
• bcn/evaluation/README.md: evaluation concepts and implementation notes
• benchmark_packs/README.md: benchmark-pack format and usage
• docs/optimization-loop.md: offline optimization loop

Quick Start

Supported local path:

git clone https://github.com/andreyka/broken-cloud-news.git
cd broken-cloud-news
./setup.sh

If you already have a populated .env, start the default stack with:

docker compose up -d

Then verify the stack:

docker compose ps

Default local endpoints:

• http://localhost:3007 -> dashboard
• localhost:5432 -> PostgreSQL

Default local services:

• scheduler -> enqueue-only control plane
• bcn -> publish worker
• ingest_worker -> collection and analysis worker
• evaluation_worker -> benchmark, shadow, and replay worker
• dashboard, postgres, egress_proxy, dns_resolver, model_bridge

Common Commands

bcn collect --source all
bcn analyze
bcn write --mode regular_daily_briefing
bcn shadow --candidate-overrides bcn/config/shadow_nemotron_bridge.json --store-db
bcn simulate --limit 30
bcn benchmark --cases benchmark_packs/core_v1.json

The full CLI surface, including recovery and review commands, is documented in docs/cli.md.

Repository Layout

Notes

• setup.sh is the supported bootstrap path for local development because it writes the .env file consumed by Compose.
• The architecture diagrams were moved to ARCHITECTURE.md so they can stay detailed without turning this file into an operator runbook.