Opticat

Know what to read, who to talk to, and what to avoid — on day one.

Opticat builds a living onboarding brief from your repo's Git history. Engineers sign in with GitHub, pick a repo, and get three things:

1. A three-act onboarding brief — the story of your codebase through its commits and PRs
2. A guided interactive code tour — walks through recent history with AI explanations, diffs, and inline chat
3. A narrated slideshow — animated presenter gives a 5-minute codebase overview with voice narration

Every insight is anchored to real Git evidence: commits, PRs, blame, and CI status.

Getting Started

Prerequisites

• Node.js 18+
• A GitHub OAuth app (for authentication)
• A Supabase project
• A Google Gemini API key

Setup

1. Clone the repo and install dependencies:

git clone https://github.com/Jeremyliu-621/onboarding.git
cd onboarding
npm install

2. Create .env.local with the following variables:

NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=<generate-a-secret>
GITHUB_CLIENT_ID=<your-github-oauth-client-id>
GITHUB_CLIENT_SECRET=<your-github-oauth-client-secret>
GEMINI_API_KEY=<your-gemini-api-key>
NEXT_PUBLIC_SUPABASE_URL=<your-supabase-url>
NEXT_PUBLIC_SUPABASE_ANON_KEY=<your-supabase-anon-key>
SUPABASE_SERVICE_ROLE_KEY=<your-supabase-service-role-key>

3. Run the development server:

npm run dev

Open http://localhost:3000 to see the app.

Stack

• Next.js 15 (App Router) + TypeScript strict mode
• Tailwind CSS for styling
• NextAuth.js with GitHub OAuth
• Octokit for GitHub REST API (PRs, commits, blame, CI, diffs)
• Supabase for data persistence
• Google Gemini (gemini-2.5-flash) for AI generation
• shiki for syntax highlighting
• Web Speech API for slideshow narration

Commands

npm run dev        # Start dev server
npm run build      # Production build
npm run typecheck  # TypeScript check
npm run lint       # ESLint

How It Works

1. User signs in via GitHub OAuth and picks a repo
2. Octokit fetches open PRs, merged PRs, commits, reviews, blame, CI runs, and file tree
3. Gemini generates a three-act brief + ordered tour steps anchored to Git history
4. Brief and tour are saved to Supabase with a shareable link
5. Tour view fetches file contents, diffs, and blame on demand per step
6. Slideshow generation creates 8–14 slides with speaker notes from the brief
7. Shared links open Brief, Tour, or Slideshow without authentication

Authors

• Jeremy Liu
• Eric Yang