Actually Relevant

News that matter to humanity. Curated with care by AI.

Crawls news sources, assesses relevance with structured AI analysis, and publishes curated stories.

Tech Stack

• Frontend: Vite + React 18 + TypeScript + Tailwind CSS
• Backend: Express + TypeScript + LangChain + OpenAI
• Database: PostgreSQL + pgvector (Prisma ORM)
• Deployment: Render.com

Local Development

Prerequisites

• Node.js 18+ and npm
• Docker (for the local PostgreSQL + pgvector database)
• OpenAI API key

Setup

1. Clone the repository:

   git clone https://github.com/OdinMB/actually-relevant.git
   cd actually-relevant

2. Install dependencies:

   cd client && npm install
   cd ../server && npm install

3. Start the database (PostgreSQL 17 + pgvector on localhost:5433, database actually_relevant_dev):

   docker compose up -d

4. Configure environment variables:

   cp server/env.example server/.env   # then fill in the values
   cp client/env.example client/.env
   # Required at minimum: DATABASE_URL, OPENAI_API_KEY, JWT_SECRET, FRONTEND_URL.
   # The template's DATABASE_URL already points at the Docker database
   #   (postgresql://ardev:...@localhost:5433/actually_relevant_dev, see docker-compose.yml).
   # See server/src/config.ts for all available settings and their defaults.

5. Start development servers:

   # Terminal 1 — Frontend (localhost:5173)
   cd client && npm run dev
   
   # Terminal 2 — Backend (localhost:3001)
   cd server && npm run dev

   Starting the backend first applies any pending migrations and regenerates the Prisma client if the schema changed (npm run db:prepare, also runnable on its own). It only does this when DATABASE_URL points at this machine (localhost, 127.0.0.1 or ::1); for any other host it warns and skips. Set SKIP_DB_PREPARE=1 to skip it. A failing migration stops the backend from starting. See .context/database-migrations.md.

Deploying to Render.com

This project requires three services on Render: a managed PostgreSQL database, an Express backend (web service), and a React frontend (static site). The backend and frontend run on separate origins.

1. PostgreSQL Database

1. Create a new PostgreSQL instance on Render
2. Note the Internal Database URL (used by the backend service)
3. Enable pgvector — connect to the database and run:

   CREATE EXTENSION IF NOT EXISTS vector;

2. Backend (Web Service)

Field	Value
Root Directory	server
Build Command	npm install --include=dev && npx prisma generate && npx prisma migrate deploy && npm run build
Start Command	npm start
Health Check Path	/health

The build generates the Prisma client, applies any pending database migrations, and compiles TypeScript. Migrations run automatically on every deploy via prisma migrate deploy, which is a no-op when there are no pending migrations. NODE_ENV=production makes a plain npm install skip devDependencies, so the command installs them with --include=dev, and the build script installs them again itself and compiles with the lockfile's TypeScript (see .context/deployment.md).

Environment Variables:

Variable	Required	Description
DATABASE_URL	Yes	Internal PostgreSQL connection string from step 1
OPENAI_API_KEY	Yes	OpenAI API key for LLM analysis
FRONTEND_URL	Yes	Frontend URL for CORS (e.g. https://actuallyrelevant.news)
JWT_SECRET	Yes	Random string (32+ chars) for signing auth tokens
NODE_ENV	Yes	Set to production (enables secure cross-origin cookies)
PORT	No	Render sets this automatically (defaults to 10000)
PUBLIC_API_KEY	No	Static API key for public consumers (mobile apps, etc.)
LOG_LEVEL	No	Logging verbosity (default: info)

Architecture notes:

• Cron jobs run in-process via node-cron — no separate worker service is needed. Job configuration lives in the job_runs database table and is managed from the admin dashboard.
• Graceful shutdown handles SIGTERM (sent by Render on deploy) by draining in-flight LLM tasks before disconnecting from the database.
• Reverse proxy trust is configured (trust proxy: 1) for correct client IP detection behind Render's load balancer.
• Cross-origin cookies use sameSite: 'none' + secure: true in production, which is required because the frontend and backend are on different Render origins. This is why NODE_ENV=production is mandatory.

3. Frontend (Static Site)

Field	Value
Root Directory	client
Build Command	npm install && npm run build
Publish Directory	dist

The build script installs devDependencies itself (npm install --include=dev, see .context/deployment.md), then type-checks, bundles with Vite, and prerenders public routes using Puppeteer. Render's build environment includes Chromium, so prerendering works without extra setup.

Rewrite rules: Add these rewrites in the Render dashboard in this exact order (Render evaluates rules top-to-bottom, first match wins):

Source	Destination	Action
/sitemap.xml	https://<backend-service>.onrender.com/api/sitemap.xml	Rewrite
/*	/index.html	Rewrite

Order is critical: The /sitemap.xml rule must appear before the catch-all /* rule. If reversed, the catch-all matches first and serves the SPA shell, resulting in a 404.

The sitemap rewrite proxies requests to the backend, which generates the sitemap dynamically from published stories. No static sitemap.xml file should exist in client/public/ — Render serves static files before applying rewrite rules.

Environment Variables:

Variable	Required	Description
VITE_API_URL	Yes	Backend URL (e.g. https://api.actuallyrelevant.news)

Post-deploy Steps

1. Set backend FRONTEND_URL to match the frontend URL (and vice versa for VITE_API_URL)
2. Database migrations run automatically during the build step — no manual action needed
3. Create the first admin user from the Render shell:

   npx tsx src/scripts/create-admin.ts

4. Add the /sitemap.xml rewrite rule to the static site (see Frontend section above)
5. Verify the health endpoint: curl https://<backend-url>/health
6. Verify the sitemap: curl https://<frontend-url>/sitemap.xml

Project Structure

actually-relevant/
├── client/          # React frontend
│   ├── src/         # Source code
│   ├── scripts/     # Build scripts (sitemap, images)
│   ├── dist/        # Built output (gitignored)
│   └── package.json
├── server/          # Express backend
│   ├── src/         # Source code
│   ├── prisma/      # Database schema and migrations
│   ├── dist/        # Built output (gitignored)
│   └── package.json
├── shared/          # Shared types and constants
├── scripts/         # Build helper shared by client and server (devDependency install)
├── .context/        # Subsystem docs (behavior and implementation) and the decision log
├── CONTRIBUTING.md  # Contribution guidelines
├── LICENSE          # AGPL v3
└── README.md        # This file

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines, including how to set up the development environment, submit pull requests, and the project's lightweight contributor agreement.

Stewardship

Actually Relevant is actively seeking a long-term institutional owner in journalism, civic tech, or effective altruism. If your organization could give this project a home, visit actuallyrelevant.news/stewardship to learn more.

License

This project is licensed under the GNU Affero General Public License v3.0. Organizations interested in running actuallyrelevant.news as a long-term steward can receive more accommodating license terms — see Stewardship.

AI-generated content markings

This software marks the content it generates as AI-generated in machine-readable form: the aiGenerated block on story objects in the public API, data-ai-generated attributes on story pages, and XMP metadata in the carousel images and PDF. See .context/ai-transparency.md.

Please do not intentionally remove or tamper with the machine-readable markings (such as metadata or watermarks) that identify content generated by this software as AI-generated.

Troubleshooting

Build Fails

Check the build logs. Common issues:

• Missing Root Directory setting on Render
• Node version mismatch — add engines to package.json if needed
• Missing npx prisma generate before server build

API Calls Fail (CORS Error)

1. Verify FRONTEND_URL is set correctly on the backend
2. Ensure it matches exactly (including https://, no trailing slash)
3. Redeploy after changing environment variables

Database Connection Fails

1. Verify DATABASE_URL is correct
2. Ensure pgvector extension is installed: CREATE EXTENSION IF NOT EXISTS vector;
3. Run migrations: npx prisma migrate deploy

Health Check

curl https://your-api-url.onrender.com/health
# Should return: {"status":"ok"}