# Project export: BasedNews This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: CruzHacks 2026 - Tagline: You can't be based if you don't know both sides of the story. - Devpost: https://devpost.com/software/basednews - GitHub: https://github.com/leo-kildani/cruzhacks2026 - Demo: https://cruzhacks2026-kappa.vercel.app/ - Video: https://www.youtube.com/embed/g2jY3BUfaoA?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Result: winner ([Sponsor - n8n] Best Use of n8n) - Team: 2 GitHub contributor(s) — leo kildani (12 commits), victor (2 commits) ## Devpost submission (written by the team) ### Inspiration In an era of polarized media, Based News was created to give readers a clearer picture of political news. We believe that informed citizens make better decisions, and informed citizens need access to unbiased information. ### What it does Based News is an AI-driven news aggregate, built to filter out the bias and deceit from mainstream media and other outlets, by conducting deep analysis on all sides of reporting. We offer general summaries of trending headlines, free from political bias, political bias analysis on different news outlets covering a headline, and a view into the public's opinion on a topic through Youtube comments. ### How we built it Our tech stack runs deep. For development of our Full-Stack application, we used Next.js App Router, with Supabase and Prisma, deployed on Vercel. To build our analysis pipelines, we utilized N8N, Parallel Web Systems, Exa.ai, and some custom JS scripts that took FOREVER to get working. We've attached diagrams depicting the systems and pipelines used in this project. ### Challenges we ran into Where do we even start. Firstly, we entered the project with a completely different idea than Based News. Our first five hours of the competition were landing on the idea of Based News and researching how in the world we were going to build it. Another challenge we ran into was honing our N8N skills and building robust workflows that function the way we intended. Additionally, we also faced the challenge of speeding up some of our workflows and API calls. The worst challenge of all was gaining insight on how the public viewed trending news. Ideally, we wanted to scrape Reddit or X, but Reddit API required you to request access and the X api rate-limited after 100 posts (NOT ENOUGH DATA). Hence, we found a workaround... Youtube Comments!!! We built our own API server using the Youtube Data API and a secret Python library to scrape all the popular comments off of videos related to specific headlines. ### Accomplishments we're proud of An accomplishment that we are extremely proud of is the Headline Ingestion and Aggregation pipeline. It took the most time to complete and ended up working (almost) exactly how we wanted it to. Another accomplishment we are extremely proud of is collaborating on the same code base without any conflicts. Not running into any merge conflicts attributes greatly to the completion of this project. ### What we learned We are baffled by the number of technologies and concepts we worked with and learned about over the course of this competition. We want to give a huge shoutout to the boys at OpenNote, who taught us so much about vector stores and web search agents, which were essential to the core functionalities of our project. ### What's next BasedNews is barely an MVP. With the complex nature of the problem we are tackling, there are several bugs and inefficiencies in our systems. Our next steps are to finish and refine the core functions of the software, and optimize where we can. ## README (from the GitHub repository) # Based News A political news aggregator that provides neutral summaries with bias ratings and public opinion analysis. Built for CruzHacks 2026. **Live Demo:** https://cruzhacks2026-kappa.vercel.app/ ## Features - **Neutral Summaries** - Direct, politically neutral summaries of the latest US political news - **7-Point Bias Scale** - Every source categorized from Far Left to Far Right - **Public Opinion** - Real-time sentiment analysis from YouTube comments ## Environment Variables Create a `.env` file in the root directory with the following variables: ```bash YOUTUBE_API_KEY=your_youtube_api_key_here ``` You can obtain a YouTube Data API key from the [Google Cloud Console](https://console.cloud.google.com/apis/credentials). ## Running the Public Opinion API (FastAPI) The public opinion analysis feature requires running a local FastAPI server exposed via ngrok. ### Prerequisites - Python 3.11+ - ngrok account with a custom domain (or use the free tier) - OpenAI API key - install dependencies from `requirements.txt` ### Start the FastAPI server In one terminal: ```bash cd python_public_opinion OPENAI_API_KEY=your_openai_api_key uvicorn main:app --host 0.0.0.0 --port 8000 ``` ### Start the ngrok tunnel In another terminal: ```bash ngrok http 8000 --domain=bursting-satyr-genuinely.ngrok-free.app ``` The FastAPI will now be accessible at `https://bursting-satyr-genuinely.ngrok-free.app`. ## API Endpoints ### 1. GET `/api/headlines` Fetches paginated headlines from the database, ordered by date (newest first). **Query Parameters:** - `skip` (optional, default: 0) - Number of headlines to skip - `take` (optional, default: 6) - Number of headlines to fetch **Response:** ```json { "headlines": [...], "hasMore": true, "totalCount": 25 } ``` **curl:** ```bash curl "https://cruzhacks2026-kappa.vercel.app/api/headlines?skip=0&take=6" ``` --- ### 2. POST `/api/headline-sources` Forwards a headline to an n8n webhook to fetch related news sources with bias ratings. Used to find additional sources covering the same story. **Request Body:** ```json { "headline": "string (required)", "description": "string (required)", "date": "string (required)" } ``` **curl:** ```bash curl -X POST "https://cruzhacks2026-kappa.vercel.app/api/headline-sources" \ -H "Content-Type: application/json" \ -d '{"headline": "Federal Judge Limits Immigration Enforcement", "description": "A federal judge issued a ruling restricting immigration agents.", "date": "2026-01-17"}' ``` --- ### 3. POST `/api/ingest/headlines` Ingests articles from 6 hardcoded RSS feeds (CNN, NYTimes, Fox News, ABC News, WSJ, LA Times) into the `Article` table. Skips duplicates based on link URL. **Request Body:** None required **Response:** ```json { "ok": true, "totalParsed": 120, "totalInserted": 15, "perFeed": [ { "url": "http://rss.cnn.com/...", "title": "CNN US", "parsed": 20, "inserted": 3 } ] } ``` **curl:** ```bash curl -X POST "https://cruzhacks2026-kappa.vercel.app/api/ingest/headlines" ``` --- ### 4. GET `/api/headlines/[id]/public-opinion` Returns public opinion analysis for a specific headline. If cached, returns immediately; otherwise, orchestrates calls to YouTube search and FastAPI analysis endpoints, then caches the result. **Path Parameters:** - `id` - The headline UUID **Response:** ```json { "summary": "Analysis of public sentiment...", "totalComments": 1500, "videosProcessed": 5, "cached": true } ``` **curl:** ```bash curl "https://cruzhacks2026-kappa.vercel.app/api/headlines//public-opinion" ``` *Note: Replace `` with an actual headline UUID from the `/api/headlines` response.* --- ### 5. POST `/api/publicopinion` Searches YouTube for videos matching a query string. Returns up to 5 most relevant videos. Used internally by the public-opinion endpoint. **Request Body:** ```json { "query": "string (required)", "publishedAfter": "ISO 8601 date string (optional)" } ``` **Response:** ```json { "videos": [ { "videoId": "abc123", "title": "Video Title", "url": "https://www.youtube.com/watch?v=abc123", "thumbnail": "https://i.ytimg.com/...", "publishedAt": "2026-01-17T12:00:00Z" } ] } ``` **curl:** ```bash curl -X POST "https://cruzhacks2026-kappa.vercel.app/api/publicopinion" \ -H "Content-Type: application/json" \ -d '{"query": "immigration enforcement ruling", "publishedAfter": "2026-01-15T00:00:00Z"}' ``` --- ### 6. POST `/api/publicopinion/analyze` Forwards YouTube video URLs to a FastAPI backend (Python service) that scrapes comments and generates an AI-powered public sentiment summary. **Request Body:** ```json { "youtube_urls": ["https://www.youtube.com/watch?v=abc123", "..."] } ``` **Response:** ```json { "summary": "Public sentiment analysis...", "total_comments": 1500, "videos_processed": 5 } ``` **curl:** ```bash curl -X POST "https://cruzhacks2026-kappa.vercel.app/api/publicopinion/analyze" \ -H "Content-Type: application/json" \ -d '{"youtube_urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"]}' ``` ## Architecture ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ Frontend │ │ (React UI) │ └─────────────────────────────┬───────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Next.js API Routes │ ├─────────────┬─────────────┬─────────────┬─────────────┬─────────────────┤ │ /headlines │ /headline- │ /ingest/ │ /headlines/ │ /publicopinion │ │ │ sources │ headlines │ [id]/public │ /analyze │ │ │ │ │ -opinion │ │ └──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴────────┬────────┘ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │PostgreSQL│ │n8n │ │RSS Feeds │ │YouTube │ │FastAPI (Python) │ │ │ │Webhook │ │ │ │Data API │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └─────────────────┘ ``` ## Tech Stack - **Frontend:** Next.js, React, Tailwind CSS - **Backend:** Next.js API Routes, Prisma ORM - **Database:** PostgreSQL (Supabase) - **External Services:** n8n, YouTube Data API, Exa.ai - **ML/AI:** FastAPI Python service with OpenAI ## Detected evidence (automated analysis) Indexed codebase: 27 recognized source files, 94 KB. - CSS (language) — detected in the code - FastAPI (technology) — detected in the code - Next.js (technology) — detected in the code - OpenAI (technology) — detected in the code - PostgreSQL (technology) — detected in the code - Python (language) — detected in the code - React (technology) — detected in the code - SQL (language) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code - Supabase (technology) — claimed on Devpost, not found in the code - Vercel (technology) — claimed on Devpost, not found in the code ## Codebase structure (from repository index) ### Files (39 of 39) ``` .gitignore app/about/page.tsx app/api/headline-sources/route.ts app/api/headlines/[id]/public-opinion/route.ts app/api/headlines/route.ts app/api/ingest/headlines/route.ts app/api/publicopinion/analyze/route.ts app/api/publicopinion/route.ts app/globals.css app/layout.tsx app/page.tsx components.json components/footer.tsx components/header.tsx components/headline-sources-modal.tsx components/headlines-section.tsx components/ui/button.tsx components/ui/card.tsx components/ui/separator.tsx eslint.config.mjs lib/parse-rss.ts lib/prisma.ts lib/rss-feed.csv lib/utils.ts next.config.ts out.txt package.json postcss.config.mjs prisma.config.ts prisma/migrations/20260117092326_add_article/migration.sql prisma/migrations/20260118045706_add_processed_field/migration.sql prisma/migrations/20260118052304_add_headlines_table/migration.sql prisma/migrations/migration_lock.toml prisma/schema.prisma python_public_opinion/Dockerfile python_public_opinion/main.py python_public_opinion/requirements.txt README.md tsconfig.json ``` ### Dependencies - package.json: @prisma/adapter-pg@^7.2.0, @prisma/client@^7.2.0, @radix-ui/react-separator@^1.1.8, @radix-ui/react-slot@^1.2.4, @tailwindcss/postcss@^4, @types/node@^20.19.30, @types/pg@^8.16.0, @types/react@^19, @types/react-dom@^19, class-variance-authority@^0.7.1, clsx@^2.1.1, csv-parse@^6.1.0, dotenv@^17.2.3, eslint@^9, eslint-config-next@16.1.3, lucide-react@^0.562.0, next@16.1.3, pg@^8.17.1, prisma@^7.2.0, react@19.2.3, react-dom@19.2.3, rss-parser@^3.13.0, tailwind-merge@^3.4.0, tailwindcss@^4, tw-animate-css@^1.4.0, typescript@^5 - python_public_opinion/requirements.txt: fastapi, openai@>=1.0.0, uvicorn[standard], youtube-comment-downloader ### Recent commits (newest first) - modify readme - Victorbranch2 (#9) - implement public opinion feature to frontend (#8) - package.json fix - update fastapi to use ngrok reverse proxy (#7) - added related sources, general summary, and political bias of releveant topics (#6) - implement python fastapi for youtube comment analysis; use youtube data api to retrieve urls (#5) - Frontend (#4) - add headlines to db (#3) - Headlines agg api (#2) - working rss parser on open rss files (#1) - init ## Key source files (fetched from GitHub, selected and truncated for size) ### package.json ``` { "name": "cruzhacks2026", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev", "build": "prisma generate &&next build", "start": "next start", "lint": "eslint" }, "dependencies": { "@prisma/adapter-pg": "^7.2.0", "@prisma/client": "^7.2.0", "@radix-ui/react-separator": "^1.1.8", "@radix-ui/react-slot": "^1.2.4", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "csv-parse": "^6.1.0", "dotenv": "^17.2.3", "lucide-react": "^0.562.0", "next": "16.1.3", "pg": "^8.17.1", "react": "19.2.3", "react-dom": "19.2.3", "rss-parser": "^3.13.0", "tailwind-merge": "^3.4.0" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20.19.30", "@types/pg": "^8.16.0", "@types/react": "^19", "@types/react-dom": "^19", "eslint": "^9", "eslint-config-next": "16.1.3", "prisma": "^7.2.0", "tailwindcss": "^4", "tw-animate-css": "^1.4.0", "typescript": "^5" } } ``` ### python_public_opinion/requirements.txt ``` fastapi uvicorn[standard] youtube-comment-downloader openai>=1.0.0 ``` ### python_public_opinion/Dockerfile ``` FROM python:3.11-slim # Set working directory WORKDIR /app # Set environment variables ENV PYTHONDONTWRITEBYTECODE=1 ENV PYTHONUNBUFFERED=1 # Install dependencies COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # Copy application code COPY main.py . # Expose port EXPOSE 8000 # Run the application CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT:-8000}"] ``` ### app/layout.tsx ```typescript import type { Metadata } from "next"; import { Geist, Geist_Mono } from "next/font/google"; import "./globals.css"; import { Header } from "@/components/header"; import { Footer } from "@/components/footer"; const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"], }); const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"], }); export const metadata: Metadata = { title: "Based News | Unbiased Political News Aggregator", description: "Based News delivers unbiased, technology-driven political news aggregation. Get deeper insights into US politics with neutral analysis and transparent methodology.", keywords: ["news", "politics", "unbiased", "aggregator", "US news", "neutral"], }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return (
{children}