A full-stack application that fetches Hacker News articles and classifies them by topic using OpenAI. Features a modern React/Svelte frontend with user authentication via Google/GitHub OAuth.
Note: The data pipeline (ETL) has been moved to a separate repository: rogerchucker/hn-data
- AI-Powered Classification: Automatically categorizes HN articles using OpenAI GPT models
- User Authentication: Google and GitHub OAuth support
- Personalization: Save read/bookmarked articles, customize category preferences
- Modern UI: Responsive React frontend with dark/light theme support
- Containerized: Ready for deployment with Podman/Docker
- Node.js 18+
- Python 3.13+
- uv (Python package manager)
- Podman or Docker (optional, for containerized deployment)
- Supabase CLI (for local database)
git clone https://github.com/rogerchucker/hn-feed.git
cd hn-feed
# Copy environment template
cp .env.example .envEdit .env and add your API keys:
- Required:
OPENAI_API_KEY- Get from OpenAI Platform - Optional: Google/GitHub OAuth credentials for user authentication
# Start local Supabase instance
supabase start# Start all services
podman-compose up -d
# View logs
podman-compose logs -fOpen http://localhost
Backend (port 9080):
source .venv/bin/activate
uv sync
uv run uvicorn hn-backend.main:app --reload --port 9080Frontend (port 5173):
cd frontend
npm install
npm run dev├── frontend/ # React/Svelte UI (Vite + nginx)
├── hn-backend/ # FastAPI backend
│ ├── auth/ # OAuth (Google, GitHub)
│ ├── connectors/ # Data source connectors
│ ├── db/ # Database layer (Supabase)
│ └── routes/ # API routes
├── supabase/ # Database migrations
└── pyproject.toml # Python dependencies
| Endpoint | Description |
|---|---|
GET /api/news |
Fetch classified articles |
GET /api/topics |
List available categories |
GET /health |
Health check |
GET /auth/google/login |
Google OAuth login |
GET /auth/github/login |
GitHub OAuth login |
GET /me |
Current user info |
| Parameter | Description | Default |
|---|---|---|
source |
Data source | hn |
limit |
Number of articles (1-100) | 30 |
topics |
Comma-separated topic filter | all |
bust_cache |
Bypass cache | false |
This project uses uv for Python package management:
# Install dependencies
uv sync
# Add a new dependency
uv add <package>
# Add a dev dependency
uv add --dev <package>
# Run scripts
uv run python <script.py>Frontend:
cd frontend
npm test # Run once
npm run test:watch # Watch mode
npm run test:coverage # Coverage reportBackend:
uv run pytest hn-backend/tests -v# Build images
podman-compose build
# Start services
podman-compose up -d
# Stop services
podman-compose down
# View logs
podman-compose logs -f backendSee .env.example for all available configuration options.
| Variable | Description |
|---|---|
OPENAI_API_KEY |
OpenAI API key for classification |
| Variable | Description | Default |
|---|---|---|
OPENAI_MODEL |
OpenAI model | gpt-4o-mini |
SESSION_SECRET |
Session encryption key | dev default |
GOOGLE_CLIENT_ID |
Google OAuth client ID | - |
GOOGLE_CLIENT_SECRET |
Google OAuth secret | - |
GITHUB_CLIENT_ID |
GitHub OAuth client ID | - |
GITHUB_CLIENT_SECRET |
GitHub OAuth secret | - |
SUPABASE_URL |
Supabase URL | localhost |
SUPABASE_KEY |
Supabase anon key | local dev key |
- Frontend: React 18, Svelte 5, Vite, TailwindCSS
- Backend: FastAPI, Pydantic, Python 3.13
- Database: PostgreSQL (Supabase)
- AI: OpenAI GPT-4o-mini
- Auth: Google OAuth, GitHub OAuth
- Containers: Podman/Docker
- Package Manager: uv (Python), npm (Node.js)
Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.
If you discover a security vulnerability, please see our Security Policy for reporting instructions.
This project is licensed under the MIT License - see the LICENSE file for details.