ContextPack - Instant AI-Ready Context Bundles for Any GitHub Repo

Core User Journey

1. User lands on homepage and sees a 'Paste GitHub URL' input pre-populated with an example repo. 2. User pastes their repo URL, selects token budget (8k/32k/100k) and output format (Markdown/Claude XML/Cursor). 3. User clicks 'Generate Context' — Next.js API route checks Redis cache, fetches repo tree via Octokit if not cached, scores and ranks all files. 4. System fetches blob content for top-ranked files up to the token budget, compresses and formats the bundle. 5. User sees a live preview panel with architecture summary, ranked file tree, and key file snippets populate within 30 seconds. 6. User clicks 'Copy to Clipboard', pastes directly into Claude, Cursor, or Copilot, and immediately receives context-aware AI responses. 7. Authenticated users see a 'Save Profile' button — on next visit, one-click regeneration from their saved repo profile.

Architecture Pattern

JAMstack with server-side GitHub API proxy enforcing security and rate limit boundaries. User requests hit Next.js API routes which check Redis cache before calling GitHub REST API — keeping all OAuth tokens server-side and never exposed to the client. The file importance ranker runs as a lightweight in-process Node.js graph algorithm on the fetched tree metadata. Blob content is fetched only for top-ranked files up to the token budget. Generated bundles are returned to the client for display and optionally persisted to Supabase for authenticated users. Vercel Edge Functions handle the public URL parser for low-latency global response.

Data Model

User {id UUID PK, githubId string UNIQUE, email string, plan enum(free|pro|teams), stripeCustomerId string nullable, createdAt timestamp}. ContextProfile {id UUID PK, userId UUID FK→User, repoUrl string, repoName string, defaultFormat enum(markdown|claude_xml|cursor_rules), defaultTokenBudget int, webhookId string nullable, lastGeneratedAt timestamp}. ContextBundle {id UUID PK, profileId UUID FK→ContextProfile nullable, content text, format enum, tokenCount int, createdAt timestamp}. SharedLink {id UUID PK, bundleId UUID FK→ContextBundle, slug string UNIQUE, expiresAt timestamp nullable, viewCount int}. No raw source code stored beyond the active generation session — only metadata and the final generated bundle text.

Integration Points

GitHub REST API (recursive repo tree, blob content fetch, git commits log for recency scoring), GitHub OAuth (user authentication and private repo scope consent), GitHub Webhooks (V3: auto-refresh context on push events), Anthropic Claude Haiku API (optional AI-generated architecture summary header), Stripe API (Pro and Teams subscription billing and webhook events), Supabase (PostgreSQL for user and profile data, Auth for GitHub OAuth, Row Level Security for bundle access control), Upstash Redis (serverless repo tree caching with TTL), Tiktoken (client-side and server-side token counting)

V1 Scope Boundaries

V1 excludes: private repos, saved context profiles, team sharing, Claude XML and Cursor .cursorrules output formats, AI-generated architecture summaries, GitHub webhook auto-refresh, VS Code or Cursor extensions, GitLab or Bitbucket support, Stripe billing. V1 includes: public GitHub repos only, up to 500 files per repo, markdown output format only, token budget slider (8k/32k/100k) with Tiktoken-based compression, copy-to-clipboard with token count display, 3 free uses without auth tracked via cookie, GitHub OAuth gate on 4th use, Redis caching of repo tree data, basic error states for repo not found and rate limit exceeded.

Success Definition

ContextPack is successful when 500 developers use it in a given month, at least 8% convert to a paid Pro plan, generation time stays under 30 seconds for repos under 500 files, and NPS exceeds 45 — with qualitative evidence that users report meaningfully better AI coding session outcomes compared to their previous manual context approach.

Challenges

Handling very large monorepos without hitting GitHub API rate limits (5,000 req/hour) requires aggressive batching and caching strategies. Intelligently ranking file importance without reading every file demands a heuristic graph algorithm that must be calibrated across many language ecosystems. Keeping context fresh as repos evolve requires webhook infrastructure and re-generation logic. Competing with native context features being added directly into tools like Cursor and GitHub Copilot Workspace represents a long-term existential risk that requires differentiation on shareability, cross-tool portability, and team collaboration features.

Avoid These Pitfalls

Never expose GitHub OAuth tokens or API keys in client-side code or browser network requests — always proxy all GitHub API calls through Next.js API routes and store tokens server-side only in encrypted session cookies or Supabase Auth. Do not attempt to support all output formats (Claude XML, Cursor, Copilot, markdown) in V1 — ship markdown only, validate that users get value, then add formats in V2 based on actual user requests rather than assumption. Do not skip GitHub API rate limit handling — large monorepos can exhaust the 5,000 req/hour authenticated limit quickly; implement exponential backoff, blob fetch batching, and aggressive Redis caching before launch or the product will fail visibly on popular repos.

Security Requirements

All GitHub OAuth access tokens stored exclusively server-side via Supabase Auth session management — never written to client localStorage, cookies accessible to JavaScript, or returned in API responses. Private repo access requires explicit user OAuth consent with a clear UI explanation of which scopes are requested and why before redirecting to GitHub. Generated context bundles for authenticated users stored encrypted at rest in Supabase with Row Level Security policies ensuring users can only access their own bundles. Public unauthenticated endpoint rate-limited to 3 generations per IP per hour via Upstash Redis counter to prevent abuse and GitHub API quota exhaustion.

Infrastructure Plan

All stateless compute hosted on Vercel Pro (Next.js server components, API routes, and Edge Functions for the URL parser) — scales to zero when idle and handles traffic spikes without configuration. Supabase Pro provides PostgreSQL for persistent user and bundle data, built-in GitHub OAuth via Supabase Auth, and Row Level Security for data isolation. Upstash Redis provides serverless pay-per-request caching for repo tree data with automatic TTL expiry. CI/CD via Vercel's GitHub integration — every push to main triggers automatic preview deployment, every merge triggers production deployment with zero downtime.

Performance Targets

Target 500 DAU at launch with headroom for 5,000 DAU without architecture changes. Under 30 seconds end-to-end generation time for repos up to 500 files on first generation with no cache. Under 5 seconds for cached repos within the 1-hour Redis TTL. Under 100ms UI response for token budget slider adjustment (purely client-side Tiktoken recalculation on already-fetched data). Under 200ms TTFB on the homepage via Vercel Edge CDN. 99.5% monthly uptime target leveraging Vercel and Supabase SLA guarantees.