BeFriend

A personal daily technology news + content tool.

It finds recent tech news matching your interests, researches and verifies the important stories against reliable sources, and drafts Twitter/X, LinkedIn, and Medium content for you to review, edit, and copy. It never publishes anything automatically.

Accuracy > Interestingness > Virality

How it works

Fetch news → remove duplicates → group into stories → rank by your interests
   ↓
Select a story → research it → verify claims → show confirmed/uncertain
   ↓
Generate Twitter/X + LinkedIn + Medium drafts → edit → fact check → copy

Tech stack

• Frontend: Next.js + TypeScript + Tailwind CSS
• Backend: Python + FastAPI + SQLAlchemy
• Database: PostgreSQL (SQLite works for local dev)

Getting started

1. Backend

cd backend
pip install -r requirements.txt
cp ../.env.example ../.env   # add your OPENAI_API_KEY
python scripts/seed.py       # creates default user + initial interests
python -m uvicorn app.main:app --port 8000

Or use the helper script:

backend/scripts/server.sh start   # runs detached, logs to backend/scripts/uvicorn.log
backend/scripts/server.sh stop

The API docs are at http://localhost:8000/docs.

PostgreSQL: docker compose up -d db then set DATABASE_URL=postgresql+psycopg2://befriends:befriends@localhost:5432/befriends. Without a key, news comes from RSS feeds and generated content uses structured templates.

2. Frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000. The Next.js dev server proxies /api/* to the backend on port 8000.

Deploy (single user, no signup)

The app is a personal single-user tool: you log in with a username + password set via env vars, and there is no signup.

1. Backend — build and run the Docker image (a backend/Dockerfile is included):

   docker build -t befriends-api backend
   docker run -d --name befriends-api -p 8000:8000 \
     -e DATABASE_URL=postgresql+psycopg2://befriends:befriends@db-host:5432/befriends \
     -e APP_USERNAME=you \
     -e APP_PASSWORD='a-strong-password' \
     -e APP_SECRET='a-long-random-secret' \
     -e OPENAI_API_KEY=... \
     -e OPENAI_BASE_URL=... \
     -e LLM_MODEL=... \
     -e GEMINI_API_KEY=... \
     befriends-api

   PostgreSQL must be reachable (docker compose up -d db works for a local host). Without a database, SQLite still works if you pass DATABASE_URL=sqlite:///data/befriend.db.

2. Frontend — build with the backend URL baked into the proxy target, then serve with Node:

   cd frontend
   NEXT_PUBLIC_API_URL=https://api.your-domain.com npm run build
   npm start        # serves on :3000

   Put npm start behind any long-lived host (a small VPS, Railway, Render, Fly.io). The backend needs long request timeouts — /api/briefs/run can take a minute or more, so a serverless frontend proxy (e.g. Vercel's) will time it out.

3. First run — python scripts/seed.py creates the default user + initial interests. There is no signup; credentials come only from APP_USERNAME/APP_PASSWORD.

Env vars

Variable	Purpose
APP_USERNAME	Login username (default Mohit)
APP_PASSWORD	Login password (required)
APP_SECRET	Signs login tokens — set a long random value
APP_TOKEN_TTL	Token lifetime in seconds (default 7 days)
NEXT_PUBLIC_API_URL	Backend URL the frontend proxy targets (default http://localhost:8000)

Daily flow

1. Open the app → Run Daily Brief → wake up to ~10 relevant tech stories.
2. Open a story → review the sources → Research Story → see confirmed facts, company claims, and what's uncertain.
3. Add personal thoughts → Generate All → review the Twitter/X, LinkedIn, and Medium drafts.
4. Edit → Regenerate (e.g. "Make shorter", "Remove hype") → Copy → paste where you publish.

Project layout

backend/
  app/api/        FastAPI routers (interests, briefs, stories, research, drafts, settings)
  app/models/     SQLAlchemy models (DATBASE.md schema)
  app/services/   news collection, ranking, research, verification, generation, fact-checker
  prompts/        Versioned LLM prompt templates (prompt.md)
  tests/          Pytest suite (testing.md)
frontend/
  app/            Next.js pages: /, /saved, /history, /settings, /stories/[id]
  components/     Navigation, StoryCard
  lib/api.ts      Typed API client
docs/             Product specs and design docs (PRD, Design, API, DATBASE, ui, prompt, content, verification, testing)

Specs

The product requirements and design live as markdown in docs/:

• docs/PRD.md — requirements
• docs/Design.md — architecture
• docs/DATBASE.md — database schema
• docs/API.md — API spec
• docs/ui.md — UI spec
• docs/prompt.md — AI prompts
• docs/content.md — content generation rules
• docs/verification.md — research & verification rules
• docs/testing.md — test strategy

Testing

cd backend && PYTHONPATH=. python3 -m pytest tests/ -q

Security & safety rules enforced in code

• Never auto-publishes.
• A claim with no evidence can never be marked confirmed.
• Generated drafts are checked against the research report; unsupported claims are flagged before you copy.
• No secrets are stored in the repo — API keys live in .env.