Technology Stack

Frontend

Backend

Infrastructure & Deployment

Vercel Configuration

• Region: iad1 (US East) for optimal GitHub API latency
• Function Duration: 30 seconds max for API routes
• Edge Runtime: Used for embed image generation routes

Key Dependencies Explained

@octokit/rest (v21.0.2)

I chose Octokit as the GitHub API client because:

• It's the official SDK maintained by GitHub
• Provides TypeScript definitions out of the box
• Handles authentication, rate limiting headers, and pagination
• Abstracts away the complexity of the REST API

GitHub GraphQL API

I added GraphQL alongside REST to optimize the most expensive operation — commit history:

• A single GraphQL query replaces 51+ REST API calls for fetching commit details
• Reduces rate limit consumption by ~98% for the commit-fetching path
• Falls back to REST automatically if GraphQL fails
• Pages history with cursor-based after/endCursor (GitHub caps history(first:) at 100 per page) to deepen up to ~2,500 commits when GitHub won't serve /stats/code_frequency — used to compute accurate line totals for repos where the statistics API returns 422

Cloudflare Worker GitHub proxy (optional)

When NEXT_PUBLIC_GITHUB_PROXY_URL is set, unauthenticated and embed requests are routed through a companion Cloudflare Worker instead of calling GitHub directly:

• Lifts anonymous users from GitHub's 60/hr cap to the authenticated 5,000/hr limit without exposing a token
• The token lives only as a Worker secret; the worker enforces an origin allowlist, a per-IP Durable Object rate limit, and read-only access
• Server-side callers authenticate with the server-only GITHUB_PROXY_SECRET via proxyAuthHeaders() (lib/proxy-auth.ts); browser callers are authorized by Origin, so the secret never enters the client bundle

next-auth (v5.0.0-beta.25)

I'm using the v5 beta of NextAuth (now Auth.js) because:

• Native App Router support with server-side auth checks
• Simplified configuration compared to v4
• JWT-based sessions without database dependency
• Easy access token extraction for API calls
• Type-safe session augmentation via next-auth.d.ts

zod (v4.3.5)

I added Zod for API input validation because:

• Runtime type checking at API boundaries complements TypeScript's compile-time checks
• Supports complex validation (GitHub URL parsing with multiple formats)
• Produces clear, user-friendly error messages
• Schema-first approach documents expected inputs

recharts (v2.15.0)

I selected Recharts for data visualization because:

• React-native components that integrate well with the stack
• Responsive by default with ResponsiveContainer
• Good documentation and TypeScript support
• Customizable tooltips and legends

lucide-react (v0.468.0)

Lucide provides the iconography because:

• Consistent, clean design language
• Tree-shakeable - only imports icons used
• Drop-in replacement for Feather icons
• Active maintenance and regular updates

Development Dependencies

Runtime Requirements

• Node.js: >= 18.17.0 (required for Next.js 15)
• npm: Package management (lock file included)

Environment Variables

Build & Runtime

Development

npm run dev          # Start with Turbopack

Production

npm run build        # Next.js production build
npm run start        # Start production server

Linting

npm run lint         # ESLint check

Design System

I implemented a custom GitHub-inspired dark theme using Tailwind CSS:

colors: {
  github: {
    dark: '#0d1117',      // Main background
    darker: '#010409',    // Darker accents
    border: '#30363d',    // Border color
    accent: '#238636',    // Primary green
    'accent-hover': '#2ea043',
    muted: '#8b949e',     // Secondary text
    link: '#58a6ff',      // Links
    text: '#c9d1d9',      // Primary text
    card: '#161b22',      // Card backgrounds
  }
}

Typography

• Sans-serif: Inter for UI text
• Monospace: JetBrains Mono for code/data

Custom CSS Features

• Glass morphism card effects with backdrop blur
• Animated gradient backgrounds
• Staggered fade-in animations for stats
• Custom scrollbar styling
• Hover lift effects on stat cards
• Slow pulse, gradient, and float animations via extended keyframes

Component Library

The ui/ directory provides a reusable component system:

• Card — Compound component (Card, CardHeader, CardTitle, CardContent, CardFooter) with default, glass, and stat variants
• LoadingSkeleton — Full-page spinner, card skeleton, and stats grid skeleton
• RepoInput — Form with URL parsing and validation
• PrivacyNotice — Dismissable privacy disclosure banner

Architecture Overview

System Architecture Diagram

graph TB
    subgraph Client["Client Layer"]
        Browser[Web Browser]
        URL[URL Parameters]
    end

    subgraph Frontend["Frontend - Next.js 15 App Router"]
        SessionCtx[SessionProvider<br/>Auth Context]

        subgraph Pages["Pages"]
            PublicPage["(public)/page.tsx<br/>Repo Search"]
            Dashboard["dashboard/page.tsx<br/>User Dashboard"]
            RepoPage["repo/[owner]/[name]/page.tsx<br/>Server Component + Metadata<br/>→ RepoPageClient.tsx"]
        end

        subgraph Components["Components"]
            subgraph Layout["layout/"]
                Header[Header]
                Footer[Footer]
            end
            subgraph UIComp["ui/"]
                Card[Card]
                RepoInput[RepoInput]
                LoadingSkeleton[LoadingSkeleton]
                PrivacyNotice[PrivacyNotice]
            end
            subgraph Features["features/"]
                StatsOverview[stats/StatsOverview]
                LanguageBreakdown[stats/LanguageBreakdown]
                CodeFrequency[stats/CodeFrequencyChart]
                CommitHistory[commits/CommitHistory]
                Contributors[contributors/ContributorsList]
                UserRepos[repos/UserReposList]
            end
            subgraph EmbedComp["embed/"]
                EmbedShare[EmbedShare Modal]
            end
            subgraph Effects["effects/"]
                Particles[ParticleBackground]
            end
        end
    end

    subgraph API["API Layer - Next.js Route Handlers"]
        AuthRoute["/api/auth/[...nextauth]"<br/>NextAuth Handlers]
        RepoRoute["/api/repo"<br/>Repository Analysis]
        StatsRoute["/api/repo/stats"<br/>Stats Polling]
        UserReposRoute["/api/user/repos"<br/>User Repositories]

        subgraph Embed["Embed Image Generation"]
            EmbedStats["/api/embed/stats"]
            EmbedCodeStats["/api/embed/code-stats"]
            EmbedLangs["/api/embed/languages"]
        end
    end

    subgraph Services["Service Layer"]
        GitHubLib[lib/github.ts<br/>GitHub API Wrapper<br/>REST + GraphQL]
        AuthConfig[auth.ts<br/>NextAuth Configuration]
        CacheLib[lib/cache.ts<br/>TTL Cache]
        Validations[lib/validations.ts<br/>Zod Schemas]
        FormatLib[lib/format.ts<br/>Formatting Utils]
        EmbedUtils[lib/embed-utils.tsx<br/>Embed Widget Helpers]
        StructuredData[lib/structured-data.ts<br/>JSON-LD Schemas]
    end

    subgraph External["External Services"]
        GitHubREST[GitHub REST API<br/>via Octokit]
        GitHubGraphQL[GitHub GraphQL API]
        GitHubOAuth[GitHub OAuth<br/>Authentication]
        Vercel[Vercel Edge Network<br/>CDN + Hosting]
    end

    Browser --> Pages
    URL --> Pages
    SessionCtx --> Pages
    Pages --> Components

    PublicPage --> RepoRoute
    Dashboard --> UserReposRoute
    RepoPage --> RepoRoute
    CodeFrequency --> StatsRoute
    Pages --> AuthRoute

    RepoRoute --> GitHubLib
    RepoRoute --> Validations
    StatsRoute --> GitHubLib
    UserReposRoute --> GitHubLib

    AuthRoute --> AuthConfig
    AuthConfig --> GitHubOAuth

    GitHubLib --> GitHubREST
    GitHubLib --> GitHubGraphQL
    GitHubLib --> CacheLib

    Embed --> GitHubREST
    Embed --> EmbedUtils
    Embed --> Vercel

    RepoRoute --> CacheLib

Routing Architecture

graph LR
    subgraph Public["Public Routes"]
        Home["/ — Repo search + analysis"]
        About["/about — Info hub: how-it-works, widget guide, FAQ"]
    end

    subgraph Protected["Protected Routes"]
        DashboardRoute["/dashboard — User repos"]
    end

    subgraph Dynamic["Dynamic Routes"]
        RepoRoute["/repo/[owner]/[name] — Repo stats"]
    end

    subgraph APIRoutes["API Routes"]
        Auth["/api/auth/*"]
        Repo["/api/repo"]
        Stats["/api/repo/stats"]
        UserRepos["/api/user/repos"]
        EmbedAPI["/api/embed/*"]
    end

    Home -->|Sign in| DashboardRoute
    DashboardRoute -->|Select repo| RepoRoute
    Home -->|Enter URL| RepoRoute
    DashboardRoute -->|Auth guard| Home

    RepoRoute --> Repo
    RepoRoute --> Stats
    DashboardRoute --> UserRepos
    Home --> Repo

Data Flow Diagram

sequenceDiagram
    participant User
    participant Browser
    participant NextJS as Next.js App
    participant API as API Routes
    participant Cache as TTL Cache
    participant GitHub as GitHub API

    User->>Browser: Enter repository URL
    Browser->>NextJS: Navigate / Submit form
    NextJS->>API: POST /api/repo

    alt Unauthenticated Request
        API->>Cache: Check cache
        alt Cache Hit
            Cache-->>API: Return cached data
        else Cache Miss
            API->>GitHub: Fetch via Cloudflare proxy (shared 5000 req/hr, per-IP throttled)
            Note over API,GitHub: REST for repo info + GraphQL for commits
            GitHub-->>API: Repository stats
            API->>Cache: Store result (10 min TTL)
        end
    else Authenticated Request
        API->>GitHub: Fetch directly with user token (5000 req/hr limit)
        Note over API,GitHub: REST for repo info + GraphQL for commits
        GitHub-->>API: Repository stats + private repos
    end

    API-->>NextJS: Analysis results
    NextJS-->>Browser: Render visualizations

    Note over Browser,NextJS: Code frequency may need polling

    opt Stats Computing (202 response)
        Browser->>API: Poll /api/repo/stats
        API->>GitHub: Retry stats request
        GitHub-->>API: Stats ready or 202
        API-->>Browser: Data or retry signal
    end

Component Architecture

components/
├── index.ts                    # Barrel exports for clean imports
├── layout/                     # Page structure components
│   ├── Header.tsx              # Navigation, auth state, branding
│   └── Footer.tsx              # Attribution and tech stack info
├── ui/                         # Reusable atomic UI components
│   ├── Card.tsx                # Card system (default/glass/stat variants)
│   ├── LoadingSkeleton.tsx     # Loading states, spinners, skeletons
│   ├── RepoInput.tsx           # Repository URL input form
│   └── PrivacyNotice.tsx       # Privacy disclosure banner
├── features/                   # Domain-specific feature components
│   ├── about/
│   │   ├── AboutContent.tsx        # Assembles the /about info hub
│   │   ├── AboutIntro.tsx          # "What is RepoLens" section
│   │   ├── HowItWorks.tsx          # Methodology + engineering notes
│   │   ├── WidgetGuide.tsx         # Interactive embed-widget guide
│   │   ├── FaqAccordion.tsx        # Collapsible FAQ
│   │   └── widgets.ts              # Widget metadata + snippet builders
│   ├── stats/
│   │   ├── StatsOverview.tsx       # Stars, forks, watchers grid
│   │   ├── LanguageBreakdown.tsx   # Color-coded language bar
│   │   └── CodeFrequencyChart.tsx  # Additions/deletions area chart
│   ├── commits/
│   │   └── CommitHistory.tsx       # Commit log with details
│   ├── contributors/
│   │   └── ContributorsList.tsx    # Top contributors grid
│   └── repos/
│       └── UserReposList.tsx       # User's repo dashboard
├── embed/
│   └── EmbedShare.tsx          # Widget embed code generator modal
└── effects/
    └── ParticleBackground.tsx  # Animated background particles

Key Architectural Decisions

1. Next.js 15 App Router with Route Groups

I chose Next.js 15's App Router because it provides the best developer experience for a React application that needs both client-side interactivity and server-side data fetching. The refactored routing uses:

• Route groups (public) for unauthenticated pages without affecting URLs
• Server-side layout guards in /dashboard/layout.tsx for protected routes
• Dynamic segments /repo/[owner]/[name] for deep-linkable repo analyses
• Turbopack for faster development builds

2. Feature-Sliced Component Architecture

Components are organized by domain rather than flat in a single directory:

• layout/ — structural components that appear on every page
• ui/ — generic, reusable atomic components (Card, LoadingSkeleton)
• features/ — domain-specific components grouped by feature area
• embed/ and effects/ — specialized concerns
• A barrel export (index.ts) enables clean imports from @/components

3. GraphQL + REST Hybrid API Strategy

The GitHub integration now uses both REST and GraphQL APIs:

• GraphQL fetches commit history in a single call (replacing 51+ REST calls), and pages with cursor-based after/endCursor to deepen up to 2,500 commits when accurate line totals are needed
• REST handles repo info, languages, contributors, and code frequency
• Fallback chain: GraphQL → REST → calculated approximation for code frequency
• This hybrid approach dramatically reduces API rate limit consumption

4. Cloudflare Worker Proxy for Unauthenticated Access

Anonymous visitors would otherwise hit GitHub's 60 requests/hour cap almost immediately. When NEXT_PUBLIC_GITHUB_PROXY_URL is configured, the GitHub client (lib/github.ts) and the embed data layer route unauthenticated calls through a companion Cloudflare Worker that fronts GitHub with a read-only token:

• Anonymous users share the authenticated 5,000/hr limit (the worker throttles per IP via a Durable Object) instead of 60/hr
• The token never reaches the client — it lives only as a Worker secret
• useProxy = !accessToken && !!GITHUB_PROXY_URL, so authenticated users still call GitHub directly with their own token
• Server-side calls (API routes, embed/OG generation) authenticate to the proxy with the server-only GITHUB_PROXY_SECRET, attached by proxyAuthHeaders() (lib/proxy-auth.ts); browser calls are authorized by Origin instead, so the secret never ships in the client bundle

5. Edge Runtime for Embed Image Generation

The embed routes (/api/embed/*) use the Edge runtime with next/og (Satori) for SVG-to-image generation. I made this choice because:

• Edge functions have lower cold start times than serverless functions
• Image generation needs to be fast for README embeds
• CDN caching at the edge reduces API calls significantly
• The 1-hour cache (s-maxage=3600) balances freshness with performance

6. Typed In-Memory Caching with TTL

The caching layer was extracted into a dedicated generic Cache<T> class in lib/cache.ts:

• Type-safe with generics — repoCache and statsCache are pre-configured instances
• Configurable TTL (10 min for repos, 10 min for stats) and max size (100/50 entries)
• Automatic cleanup of expired entries
• Only used for unauthenticated requests, easing pressure on the proxy's shared, per-IP-throttled budget

7. Zod Validation at API Boundaries

All API route inputs are validated with Zod schemas in lib/validations.ts:

• RepoRequestSchema handles multiple GitHub URL formats (owner/repo, full URLs, etc.)
• StatsRequestSchema validates stats polling requests
• Clear, user-friendly error messages via formatZodError()
• Validation at the boundary only — internal code trusts validated data

8. Client-Side Authentication State with NextAuth v5

I use NextAuth v5 (Auth.js) with the GitHub provider for authentication. The access token is stored in the JWT and passed to the client session. Key reasons:

• No database required — tokens exist only in signed JWTs
• Privacy-first approach — no credentials stored server-side
• The repo scope allows access to private repositories
• Session data is available on both client and server via SessionProvider

9. Parallel Data Fetching

In lib/github.ts, I fetch repository data, languages, commits, code frequency, and contributors in parallel using Promise.all(). This significantly reduces total request time compared to sequential fetching, though it increases API usage per request.

10. Progressive Enhancement for Statistics

GitHub's statistics API returns 202 while stats compute (and 422 for very large repos). Rather than blocking the UI or showing an empty chart, I:

• Render a stand-in code-frequency series immediately, derived from the per-commit additions/deletions already fetched (deriveCodeFrequencyFallback)
• Poll with exponential backoff (3s, 6s, 12s, 24s, 48s) on the client — but only when the series is genuinely pending and the commit-derived estimate doesn't already cover the repo's full history
• Deepen line totals by paginating GraphQL commit history up to 2,500 commits when GitHub won't serve /stats/code_frequency
• Use a fallback endpoint for contributors if stats aren't ready

11. URL-Based State Management

Repository selection is reflected in the URL via dynamic routes (/repo/[owner]/[name]) and query params (?repo=owner/repo). This enables:

• Shareable links to specific repository analyses
• Browser history navigation
• Bookmarkable results
• SEO benefits for public repository pages

12. SEO Infrastructure

I added a comprehensive SEO layer to improve discoverability:

• Static OG/favicon images — replaced dynamic edge-generated ImageResponse icons with pre-rendered PNGs in public/, eliminating unnecessary edge compute for images that never change
• robots.ts — allows /, disallows /api/ and /dashboard, references sitemap
• sitemap.ts — includes the static pages (homepage and /about); dynamic repo pages are effectively infinite and discovered organically
• JSON-LD structured data — WebApplication schema on every page via root layout, WebPage schema on individual repo pages via lib/structured-data.ts
• Per-page metadata — the repo page uses a server/client split so the server component can export generateMetadata() with dynamic title, description, and OG tags for each owner/name combination
• Dashboard noindex — the protected dashboard has robots: { index: false, follow: false } to prevent accidental crawling