StarLib

Turn your GitHub stars into a searchable, conversational library. Sign in with GitHub, StarLib auto-syncs your starred repositories, indexes them with embeddings, and helps you choose the right open-source project — by semantic search or by asking a built-in AI agent. Installable PWA, bilingual (en/zh).

Features

• GitHub sign-in (better-auth, OAuth App) with auto-sync of your stars.
• Semantic search over your library (Postgres + pgvector) with language / topic / star filters.
• Selection advisor agent (AI SDK) that answers only from your library, cites repos, and compares them on real metadata.
• Mobile PWA: installable, offline-aware, navy-ink design system.

Stack

Next.js 15 (App Router) · TypeScript · Tailwind v4 · coss UI · better-auth · Drizzle ORM · Postgres + pgvector · AI SDK v5 + OpenAI · next-intl · Serwist · pnpm. Frontend follows Feature-Sliced Design; the backend follows Domain-Driven Design. See docs/ — the single source of truth.

Quick start

pnpm install
make db-up            # Postgres + pgvector via Docker
make db-migrate       # apply migrations
cp .env.example .env.local   # fill in the values (see below)
make dev              # http://localhost:3000

make check runs lint, typecheck, tests, and the production build.

Configuration

Copy .env.example to .env.local and set:

Variable	Notes
DATABASE_URL	Postgres URL (matches the dev compose by default)
BETTER_AUTH_SECRET	openssl rand -base64 32
BETTER_AUTH_URL	Public origin, e.g. http://localhost:3000
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	GitHub OAuth App
OPENAI_API_KEY	Chat + embeddings
OPENAI_BASE_URL	Optional OpenAI-compatible gateway
OPENAI_CHAT_MODEL	Default gpt-4o-mini
OPENAI_EMBEDDING_MODEL	Default text-embedding-3-small
CRON_SECRET	Protects /api/cron/sync

Create the GitHub OAuth App

1. Go to https://github.com/settings/developers → OAuth Apps → New OAuth App (an OAuth App, not a GitHub App — OAuth App tokens don't expire).
2. Set Authorization callback URL to {BETTER_AUTH_URL}/api/auth/callback/github (e.g. http://localhost:3000/api/auth/callback/github).
3. Copy the Client ID and generate a Client Secret into your env.

Reading your public stars needs no extra scope. If your GitHub primary email is private, verify sign-in works with a private-email account.

Deployment

Platform-agnostic (no Vercel-only APIs):

• Vercel + Neon/Supabase: point DATABASE_URL at the pooled connection string; copy deploy/vercel.json.example to vercel.json for the cron schedule and function durations.
• Self-hosted Docker: docker compose -f deploy/docker-compose.yml up --build (app in output: "standalone" + pgvector). Run pnpm drizzle-kit migrate against the database on first deploy.

Star sync runs as time-boxed slices driven by client polling, so it fits serverless timeouts and long-lived containers alike (ADR-0005).

Documentation

• docs/project — overview, goals, architecture
• docs/frontend — Feature-Sliced Design conventions
• docs/backend — Domain-Driven Design conventions
• docs/operations — local dev, env, deployment
• docs/quality — testing strategy
• docs/decisions — ADRs