How It Was Built

This documentation explains how this AI news agent platform works, in enough depth that you should be able to rebuild it yourself from scratch. The project collects news articles, scores and classifies them with AI, generates social posts, and lets a user review everything before publishing.

The big picture

This project is two separate programs that share one database. That split is the single most important thing to understand about this project, because it explains almost every other decision.

One program is the local news agent in agents/news/run.ts. It runs on your Mac, fetches RSS feeds, de-duplicates articles, asks the AI model to classify them, ranks the results, asks the AI model to write posts, and saves the results.

The other program is the hosted Next.js dashboard on Vercel. It provides the login page, dashboard pages, and API routes. It reads the same data the agent wrote and lets you approve, reject, and publish generated content.

Both programs talk to the same Neon Postgres database. The agent writes; the dashboard reads and writes back smaller human decisions like approvals. Neither program needs to know the other exists.

A note on managing secrets

This project does not have a custom in-app screen for editing API keys, and that is a deliberate choice, not a missing feature.

Environment variables, meaning the values in your .env file locally or in Vercel's Environment Variables settings for the deployed app, are the standard, secure way to store secrets like API keys. The code reads them at startup and never stores them anywhere else.

Vercel's own dashboard already gives you everything a custom settings page would: masked values so they are never shown in full again, separate values per environment, and a change history. Building a second, custom version of that inside this app would mean this app's own database or admin panel becomes a second place secrets can leak from, for no real benefit over the one Vercel already gives you for free.

To change a secret for the deployed app, go to your project on vercel.com, open Settings, then Environment Variables, edit the value, and redeploy or wait for the next deploy. To change it locally, edit the .env file directly and restart the dev server or agent script.

Settings that are not secrets, like which topics the news agent looks for or the text of its prompts, are editable from inside the dashboard already. The Agent Config and Prompts pages store those values in the regular database because they do not need the extra protection secrets need.

Sections

Build Guide: The complete milestone-by-milestone story of how the project was built.
Architecture: The big picture: what pieces exist, why they are split the way they are, and how data moves.
System Graph: An interactive, hand-maintained map of the real architecture and service relationships.
Tech Stack: Every major package and service used, why it was chosen, what it costs, and alternatives.
File Types: The project file extensions, what each kind of file is for, and examples in this repo.
Data Flow: A step-by-step walkthrough of one daily agent run and normal dashboard interactions.
Troubleshooting: Real bugs that came up while building this, what caused them, and how they were fixed.
Process: How Claude supervised Codex, verified work, broke tasks down, and used commits.
Deploy Your Own Copy: The shortest path for a stranger to fork and deploy a free working dashboard.
Setup Guides: Practical setup steps for posting, auto-publish, local development, and tests.
Glossary: Plain-English definitions of the jargon used throughout these docs.