NutsNews Documentation
Section titled “NutsNews Documentation”Welcome to the NutsNews documentation hub.
This repository is the canonical documentation home for NutsNews web, NutsNews Worker, and NutsNews iOS. Keep product, operations, deployment, cache, automation, and environment documentation here instead of in the application repositories so documentation-only updates do not trigger app deployments.
This folder is organized by what you are trying to do: understand the product, change the platform, operate production, monitor risk, or debug problems.
Fast Paths
Section titled “Fast Paths”| Goal | Start here |
|---|---|
| Learn what NutsNews is | Project Overview |
| Understand the system | Architecture |
| Run the platform | Operations |
| Understand the VPS operating model | Infra Operations Platform |
| Bootstrap the VPS baseline | VPS Ansible Bootstrap |
| Bootstrap the backend server | Backend Bootstrap |
| Bootstrap backend credentials | Backend Credential Bootstrap |
| Run the protected backend apply workflow | Backend Protected Apply |
| Route backend.nutsnews.com | Backend Cloudflare Routing |
| Run the backend drift check | Backend Drift Check |
| Review backend host security baseline | Backend Security Baseline |
| Review backend backup and restore baseline | Backend Backup and Restore |
| Review backend monitoring baseline | Backend Monitoring |
| Review backend health report automation | Backend Health Report |
| Understand database resiliency and failover readiness | Database Resiliency |
| Run backend cleanup report or dry-run | Backend Cleanup Maintenance |
| Run fixed backend recovery checks or actions | Backend Recovery |
| Review backend OpenAI maintenance robot | Backend OpenAI Maintenance Robot |
| Review backend service baseline attestation | Backend Service Baseline |
| Operate the Supabase standby restricted probe | Supabase Standby Restricted Probe |
| Reconcile the existing Supabase standby bootstrap | Backend Postgres Failover |
| Find the worker-uplift operation owner map | Worker-Uplift Operation Map |
| Review worker-uplift RabbitMQ capacity and security | Worker-Uplift RabbitMQ Capacity And Security |
| Provision worker-uplift RabbitMQ | Worker-Uplift RabbitMQ Provisioning |
| Operate worker-uplift RabbitMQ drift, smoke, and canary workflows | Worker-Uplift RabbitMQ Operations |
| Rebuild, restore, or upgrade worker-uplift RabbitMQ | Worker-Uplift RabbitMQ Recovery |
| Operate worker-uplift services on the backend host | Worker-Uplift Service Runtime |
| Verify worker-uplift RabbitMQ metrics collection | Worker-Uplift RabbitMQ Metrics |
| Run the protected VPS baseline workflow or trigger an on-demand report | Protected Ansible Apply; Operations Portal v1 |
| Run protected VPS package maintenance or reboot | VPS Maintenance |
| Synchronize reviewed Vercel Production variables to the VPS | Vercel-to-VPS environment synchronization |
| Understand the VPS service foundation | VPS Service Foundation |
| Review production/staging VPS runtime isolation | VPS Runtime Environment Isolation |
| Review same-host staging capacity and safeguards | VPS Staging Capacity Budget |
| Rehearse or approve an immutable staging deployment | VPS Immutable Staging Deployment |
| Qualify an isolated deployed staging candidate | VPS Immutable Staging Deployment — Independent Off-VPS Qualification |
| Rehearse staging gate failures and bypass closure | Protected Ansible Apply — Gate Rehearsal And Bypass Inventory |
| Configure the protected staging hostname and credential boundary | VPS Staging Access and Credential Boundary |
| Understand the VPS operations portal | Operations Portal v1 |
| Set up or restore encrypted VPS backups | VPS Backups; VPS Restore; VPS Disaster Recovery |
| Set up Grafana Cloud observability | Grafana Cloud Observability |
| Ship a change | Deployment Checklist |
| Understand the current end-to-end release pipeline | Release Pipeline |
| Write or review production release notes | Release Notes Workflow |
| Understand the Vercel + VPS web delivery model | Dual-Target Web Deployment |
| Prepare or operate VPS-primary Cloudflare DNS failover | Dual-Target Web Deployment - Cloudflare DNS Failover Controller |
| Fix a production issue | Troubleshooting |
| Check cost and quota risk | Free-Tier Guardrails |
| Validate public API contracts | Public API Contract Tests |
| Plan a formal external public API | Public API Plan |
| Work on translations | Multi-language Summaries; Multilingual Quality and Fallbacks |
| Work on local AI | Worker Local AI Lock; see ramideltoro/nutsnews-worker |
| Operate the worker-uplift shadow runtime | Worker-Uplift Shadow Runtime |
| Investigate worker queue pressure | Worker Backpressure and Lock Safety |
| Run regression tests | Web Offline E2E; Vercel Preview Smoke Test; Worker tests live in ramideltoro/nutsnews-worker |
| Review iOS notes | iOS documentation and update notes |
Documentation Tree
Section titled “Documentation Tree”1. Start Here
Section titled “1. Start Here”These docs explain the product and the system at a high level.
| Doc | Use it for |
|---|---|
| Project Overview | Product story, mission, reader experience, and current status |
| Architecture | System components, data flow, and repository layout |
| Operations | Day-to-day operating model, admin portal, and maintenance tasks |
| Infra Operations Platform | VPS GitOps model, CI stability layer, Ops Portal goal, support-node rules, reports, and provider migration strategy |
| VPS Ansible Bootstrap | First Ubuntu VPS baseline, SSH lockout prevention, firewall, updates, logging, and recovery flow |
| Backend Bootstrap | Backend server host contract, runtime direction, repo boundaries, and initial Ansible scaffold |
| Backend Credential Bootstrap | Protected GitHub Environment setup, credential inventory, provider secret names, readiness workflow, and rollback |
| Backend Protected Apply | Manual protected backend Ansible check/apply workflow, Environment secrets, blockers, and validation |
| Backend Cloudflare Routing | DNS-only Cloudflare backend route, Caddy /healthz, protected apply order, verification, and rollback |
| Backend Drift Check | Protected read-only drift workflow, classification semantics, current evidence, and rollback boundary |
| Backend Security Baseline | Backend SSH hardening desired state, verification commands, and apply blocker |
| Backend Backup and Restore | Backend backup scope, retention, restore-test gate, secret boundary, and recovery order |
| Backend Monitoring | Backend host smoke checks, alert thresholds, log retention, and alert-delivery blocker |
| Backend Health Report | Scheduled read-only backend host reports from GitHub Actions, JSON artifacts, SMTP delivery, and rollback |
| Backend Cleanup Maintenance | Fixed-purpose backend cleanup report, dry-run, protected apply, allowlists, and protected paths |
| Backend Recovery | Fixed-purpose backend recovery checks, protected service actions, pre/postchecks, and last-run evidence |
| Backend OpenAI Maintenance Robot | Daily OpenAI-assisted maintenance scan, scan labels, issue routing, artifacts, and safety boundaries |
| Backend Service Baseline | Read-only live service inventory, public exposure policy, and re-attestation trigger |
| Supabase Standby Restricted Probe | Zero-cost forced-command backend probe boundary, activation checks, incident response, and safe evidence for the protected standby readiness workflow |
| Backend Postgres Failover | Existing production Supabase standby reconciliation workflow, safe metadata report contract, protected backfill mode, and failover boundary |
| Worker-Uplift Operation Map | Backend-owned old-to-new operation map for legacy Worker scripts, backend host operations, Grafana ownership, DNS failover separation, and worker-uplift runtime controls |
| Worker-Uplift RabbitMQ Capacity And Security | RabbitMQ release pin, queue-type decision, hard limits, access boundary, benchmark path, and recovery model for the backend-owned worker-uplift broker |
| Worker-Uplift RabbitMQ Provisioning | Protected Ansible/Compose provisioning path, topology bootstrap, credential boundary, durable probe, host-restart verification, and rollback model for the backend-owned worker-uplift broker |
| Worker-Uplift RabbitMQ Operations | Protected RabbitMQ apply guardrails, read-only drift coverage, smoke checks, private canary checks, health-report integration, artifacts, and issue #84/#91 proof paths |
| Worker-Uplift RabbitMQ Recovery | Sanitized definition exports, clean rebuild drills, stopped-volume restore drills, upgrade procedure, and health signals for the backend-owned worker-uplift broker |
| Worker-Uplift Service Runtime | Shadow-first backend worker service runtime framework, fixed protected operations, service manifest validation, and issue #85 proof plan |
| Worker-Uplift RabbitMQ Metrics | Backend Alloy RabbitMQ scrape path, bounded queue metrics, Grafana Cloud remote-write boundary, and issue #87 proof plan |
| Backend PostgreSQL Failover | Backend PostgreSQL shadow target, worker/app compatibility boundaries, parity gates, and rollback boundary |
| Protected Ansible Apply | Manual protected GitHub Actions workflow for check/apply runs against the VPS baseline, plus the separate on-demand health report workflow |
| VPS Service Foundation | Docker, Compose, /opt/nutsnews, Caddy, and public infrastructure health routing |
| VPS Runtime Environment Isolation | Separate production/staging Compose identities, state, Caddy boundary, immutable digest rule, and #118 blocker |
| VPS Staging Capacity Budget | Measured #118 capacity decision, fixed resource/test budgets, disk limitation, and post-apply verification |
| VPS Immutable Staging Deployment | Candidate schema, pre-secret trust checks, staging-only GitOps apply, deterministic non-destructive qualification, off-VPS attestation, audit evidence, and required live verification |
| VPS Staging Access and Credential Boundary | Shared-host topology, Cloudflare Access, fixed deployment identity, secret onboarding, protected apply, rollback, and live verification |
| Dual-Target Web Deployment | One application commit, Vercel and GHCR artifacts, immutable VPS promotion, staged validation, public opt-in, and rollback |
| Operations Portal v1 | Read-only VPS dashboard, local collector, public Google OAuth route, status JSON, and recovery notes |
| VPS Alert Email Policy | Stable alert identity, cooldown/escalation behavior, backup freshness semantics, and read-only troubleshooting |
| VPS Backups | Encrypted restic backups to a dedicated OneDrive rclone remote, setup secrets, status, alerts, and validation |
| VPS Maintenance | Protected package maintenance, reboot approval, post-reboot validation, and failure handling |
| VPS Restore | Restoring encrypted VPS snapshots to staging, copying selected data/config, and restore testing |
| VPS Disaster Recovery | Rebuilding on another VPS provider, restoring data, verifying, cutting over DNS, and rollback |
| Grafana Cloud Observability | Grafana Alloy telemetry, centralized OpenTofu-managed dashboards/alerts, Synthetic Monitoring, backend imports, and free-tier guardrails |
| Troubleshooting | Common failures, checks, and recovery steps |
2. Product and Reader Experience
Section titled “2. Product and Reader Experience”Public site
Section titled “Public site”| Doc | Use it for |
|---|---|
| Full Archive Search | Search behavior and archive lookup flow |
| Multi-language Summaries | Supported languages, storage, Worker generation, and API display behavior |
| Multilingual Quality and Fallbacks | Translation coverage checks, English-leak detection, admin visibility, and fallback policy |
| Public Page Translations | About, Contact, Privacy, and settings language behavior |
| Public Pages Theme Consistency | Theme behavior across public pages |
| Privacy Analytics And Consent | GA4 consent gate, allowed event taxonomy, disallowed data, retention, and rollback |
| Publisher Attribution And Content Use | Publisher credit, summary/excerpt limits, source removal workflow, and future digest/social requirements |
| Public API Plan | Future formal external public API use cases, fields, rate limits, caching, versioning, and privacy constraints |
| Sitemap Scaling Strategy | Sitemap index, article sitemap shards, crawler discovery, cache policy, and SEO audit coverage |
UI and polish
Section titled “UI and polish”| Doc | Use it for |
|---|---|
| Modern Theme UI | Current public visual direction |
| Cache Safety Update | Safe public caching behavior |
| Feed Visibility Fade Fix | Feed rendering visibility behavior |
| Home Button Update | Public navigation home button behavior |
| Page Fade Appear Update | Page transition polish |
Admin experience
Section titled “Admin experience”| Doc | Use it for |
|---|---|
| Admin Article Reviews | Accepted/rejected stories, filters, and review investigation |
| Admin Audit Log | Protected audit trail for sensitive admin changes, retention, privacy, and validation |
| Incident Response Policy | SEV1/SEV2/SEV3 definitions, alert routing, incident checklist, and post-incident review template |
| Production Readiness Dashboard | Admin green/yellow/red scorecard for shipping readiness across public API health, Worker freshness, DB growth, translations, images, backups, and CI |
| Responsive Admin Dashboards | Mobile-friendly admin dashboard patterns |
| Home Server Dashboard | /admin/home-server setup and troubleshooting |
3. Platform and Data
Section titled “3. Platform and Data”Core platform
Section titled “Core platform”| Doc | Use it for |
|---|---|
| Worker ingestion, controller, and local AI | See ramideltoro/nutsnews-worker |
| Worker Backpressure and Lock Safety | Queue visibility, Redis lock lease safety, backpressure thresholds, and worker report counters |
| Public Feed Snapshot and Edge Fallback | Supabase snapshot reads, Cloudflare KV fallback, headers, admin status, and recovery checks |
| Runtime Feature Flags | Protected shared runtime switches for archive search and optional Worker edge-snapshot publishing, with no-redeploy rollback steps |
| Supabase RLS Regression Tests | Local Supabase allow/deny policy tests for public reads, denied anonymous writes, and service-role-only database surfaces |
| RSS Source Quality | Feed quality scoring, ranking, and source decisions |
| Image Delivery | Thumbnails, image optimization, cache TTL, and category-aware non-photo fallbacks |
| Secure Image Proxy/Cache Design | Issue #105 design for optional Cloudflare image proxy/cache, domain controls, quotas, rollout, and kill switches |
| Performance and Resiliency | Caching, pagination, indexes, sharding, and reliability |
| Homepage Performance Budget | Homepage LCP, JS, CSS, image, and transfer budgets |
| Web Visual Regression Tests | Playwright screenshot baselines for public page layout states |
| Cloudflare Cache Observability | Cache policy dashboard, scheduled alerts, route expectations, and common fixes |
Data protection and recovery
Section titled “Data protection and recovery”| Doc | Use it for |
|---|---|
| Database Resiliency | Current primary/standby topology, data synchronization, failover gates, backup layers, and improvement opportunities |
| Supabase Backup Automation | Home-server backups to encrypted OneDrive |
| VPS Backups | VPS restic backups to encrypted OneDrive storage through rclone |
| VPS Restore | VPS restic restore and restore-test procedure |
| VPS Disaster Recovery | Provider-agnostic VPS rebuild and cutover runbook |
| Worker-Uplift RabbitMQ Operations | RabbitMQ protected apply, drift, smoke, private canary, and health-report operating evidence |
| Worker-Uplift RabbitMQ Recovery | RabbitMQ topology rebuild, stopped-volume restore, and upgrade procedure |
| Worker-Uplift RabbitMQ Metrics | RabbitMQ metrics collection, cardinality guardrails, and Grafana ownership boundary |
| Supabase Restore Procedure | Restore order, SQL import, and validation queries |
| Migration Release Gate | Ordered migrations, schema-drift readiness, deterministic staging fixtures, compatibility windows, and protected rollout |
| Free-Tier Guardrails | Quota, cost, and usage warning dashboard |
4. AI and Automation
Section titled “4. AI and Automation”AI providers
Section titled “AI providers”| Doc | Use it for |
|---|---|
| Worker Local AI Lock | Web-side note for the Worker repo local-AI deployment lock |
| Worker Backpressure and Lock Safety | Ingestion pressure controls, lock overlap safety, and queue/deferred report fields |
| Worker/local AI repository | See ramideltoro/nutsnews-worker |
| Multi-language Summaries | Website translation display and recovery context |
| Multilingual Quality and Fallbacks | Quality gates, daily reports, admin dashboard, and fallback behavior |
Automation and Workers
Section titled “Automation and Workers”| Doc | Use it for |
|---|---|
| Cloudflare Turnstile Contact Form | Contact form bot protection |
| GitHub Actions Automation | CI and automation workflow overview |
| GitHub Pages Wiki Publishing | Publishing docs to wiki.nutsnews.com |
5. Operations and Release Management
Section titled “5. Operations and Release Management”Deploy and maintain
Section titled “Deploy and maintain”| Doc | Use it for |
|---|---|
| Deployment Checklist | Safe release steps for web, DB, and cache |
| Release Pipeline | Current end-to-end commit, PR, Vercel, image, staging, qualification, protected promotion, production VPS, and verification pipeline |
| Release Notes Workflow | Manual release-note format, cross-repo checklist, evidence, automation boundary, and rollback notes |
| Dual-Target Web Deployment | Build identity, environment parity, image publishing, digest promotion, VPS-primary DNS failover, protected rollout, and rollback |
| Dependency Updates | npm audit, safe upgrades, Dependabot, and validation |
| Mandatory NutsNews Docs Policy | Required docs updates, release-note summaries, diagrams, and app/docs PR linkage for every NutsNews change |
| Platform Improvement Backlog | Planned platform improvement issues |
Monitoring and incidents
Section titled “Monitoring and incidents”| Doc | Use it for |
|---|---|
| Observability | Logs, errors, dashboards, and health checks |
| VPS Production Runtime 500 Incident | Correlated RSC 500 evidence, GitOps recovery, protected Supabase migration, and schema-compatible release promotion |
| Backend Health Report | Daily backend host health report, generated JSON, email delivery, and read-only evidence |
| Grafana Cloud Observability | VPS host/container/service/app/log dashboards, quota alerts, and Synthetic Monitoring setup |
| Cloudflare Cache Observability | Expected-vs-actual cache header reports and alerts |
| UptimeRobot Onboarding | External uptime monitors |
| Grafana Backup Monitoring | Backup freshness and success panels |
| PageSpeed Insights | Production performance audits |
6. Quality, Security, and Regression Tests
Section titled “6. Quality, Security, and Regression Tests”Quality checks
Section titled “Quality checks”| Doc | Use it for |
|---|---|
| Homepage Performance Budget | Build-size report, hard budgets, and common fixes |
| Web Visual Regression Tests | Screenshot snapshots, update workflow, and failure artifacts |
| Supabase RLS Regression Tests | Disposable local database tests for Supabase grants, RLS policies, and approved public/service-role access |
| Multilingual Quality and Fallbacks | Translation coverage report, language-code checks, and fallback quality rules |
| Lighthouse CI Onboarding | Lighthouse CI setup and thresholds |
| PageSpeed Insights | Manual production speed checks |
| axe Playwright Accessibility CI | Accessibility regression checks |
| SEO Structured Data Audit | SEO and structured data review |
| Sitemap Scaling Strategy | Sitemap index and shard validation for large article archives |
Security checks
Section titled “Security checks”| Doc | Use it for |
|---|---|
| CodeQL Security Scan | GitHub CodeQL setup and usage |
| Snyk Security Scan | Snyk dependency and code scanning |
| Security Hardening | CSP, browser headers, admin no-store behavior, contact form controls, and CI validation |
| Security CI Scans | CodeQL, Dependency Review, Dependabot, Gitleaks, OSV, actionlint, OpenSSF Scorecard, Lighthouse, ZAP, and manual GitHub security settings |
| Dependency Updates | Safe package update routine |
Public web regression tests
Section titled “Public web regression tests”| Doc | Use it for |
|---|---|
| Public API Contract Tests | Mocked contract checks for /api/articles, /api/search, /api/contact, sitemap, and robots |
| Web Offline E2E Regression Test | Fully mocked public web flow test before preview deploy |
| Web Public Reader Smoke Test | PR Playwright smoke coverage for home feed, infinite scroll, language switching, contact validation, public pages, and article detail |
| Web Visual Regression Tests | Public-page screenshot snapshots for desktop/mobile and representative UI states |
| Vercel Preview Smoke Test | Live PR preview checks after Vercel deploys |
| Worker Offline E2E Regression Test | See ramideltoro/nutsnews-worker |
| Worker Local AI Lock | Why the Worker repo prevents accidental OpenAI-first deploys |
7. Archive and Update Notes
Section titled “7. Archive and Update Notes”Older one-off implementation notes are kept out of the main reading path.
| Area | Location |
|---|---|
| Archived root notes | archive/ |
| Older update notes | updates/ |
| iOS update notes | ios/ |
Recommended Reading Order
Section titled “Recommended Reading Order”For a new contributor:
For production support:
For UI or reader-facing work:
Documentation Standards
Section titled “Documentation Standards”Keep docs:
- Short at the top
- Clear before detailed
- Action-oriented
- Easy to scan
- Linked from this index when they matter
- Archived when they become one-off notes
See Documentation Style Guide for naming, structure, and wording rules.
Vercel preview smoke test protection bypass
Section titled “Vercel preview smoke test protection bypass”Protected Vercel preview deployments require the GitHub Actions secret VERCEL_AUTOMATION_BYPASS_SECRET, created from Vercel Project Settings -> Deployment Protection -> Protection Bypass for Automation. The live Playwright smoke test uses this secret only as an HTTP header and does not commit it to the repo.