🏗️ Architecture Overview

The gh.gg platform is built on a modern, robust, and scalable architecture designed to deliver powerful AI-driven insights into GitHub repositories. As illustrated in the README's Architecture Diagram↗, the system is composed of several interconnected layers, each playing a critical role in data processing, user interaction, and AI computation.

Next.js App Router

At the forefront of gh.gg is the Next.js App Router, which forms the user interface layer. This architecture allows for a hybrid rendering approach:

• Server Components: These components are rendered on the server, enabling efficient data fetching directly from the backend (like the database or external APIs). They deliver fully-formed HTML to the client, improving initial page load performance and SEO.
• Client Components: These provide interactive UI elements that require client-side JavaScript, such as forms, dynamic charts, and user input handlers.
• API Routes: These are serverless functions that handle backend logic, acting as an intermediary between the client-side components and the underlying services. They are responsible for processing requests, interacting with the database, and calling external APIs.

This setup ensures a fast, responsive user experience while leveraging the benefits of server-side processing.

tRPC API Layer

Connecting the Next.js frontend to the backend services is the tRPC API Layer. tRPC is a highly efficient, type-safe RPC (Remote Procedure Call) framework.

• Type Safety: tRPC ensures end-to-end type safety between the frontend and backend. This means that data structures and function calls are validated at compile-time, significantly reducing runtime errors and improving developer productivity by providing auto-completion and static analysis.
• Seamless Integration: It allows frontend components and API routes to directly call backend procedures without manual API schema generation, behaving like local function calls.
• Efficiency: Requests are batched to optimize network calls, and only necessary data is transferred.

The tRPC layer acts as the primary communication channel, ensuring robust and reliable data exchange.

PostgreSQL Database with Drizzle ORM

The persistence layer of gh.gg is powered by a PostgreSQL database, a powerful open-source relational database. This is where all application data is securely stored, including:

• User accounts and sessions
• GitHub App installations and repository permissions
• Cached repository information
• AI analysis results (e.g., Scorecards, AI Slop reports, Developer Profiles)
• Arena battle data and developer rankings
• User subscriptions and API keys
• Wiki pages and content

Drizzle ORM (Object-Relational Mapper) is used to interact with the PostgreSQL database. Drizzle provides:

• Type-Safe Queries: It allows developers to write database queries using TypeScript, ensuring that database interactions are type-checked and less prone to errors.
• Schema Management: It handles database schema definitions and migrations, making it easier to evolve the database structure over time.
• Caching: Drizzle can be integrated with caching mechanisms to optimize data retrieval from the database.

External Services

gh.gg integrates with several critical external services to provide its core functionalities:

• GitHub API: This is the primary source of repository and user data. It's used to:

  • Fetch repository files, branches, commits, pull requests, and issues.
  • Authenticate users via OAuth.
  • Manage GitHub App installations, allowing access to private repositories and event webhooks.
  • Post automated comments on pull requests and issues.
  • The Octokit library is used for seamless interaction with the GitHub API.

• Google Gemini AI: The intelligence layer for all AI-powered analysis features. Utilizing the Vercel AI SDK, Gemini AI is employed for:

  • Generating Repository Scorecards and detailed Code Quality Reports (AI Slop detection).
  • Performing PR Code Reviews and Issue Triage with priority suggestions.
  • Creating Developer Profiles with skill assessments and development style analysis.
  • Generating Interactive Diagrams (e.g., flowcharts, sequence diagrams) and Wiki documentation.

• Stripe: Integrated for handling payments and subscription management. This enables:

  • Processing user subscriptions (Developer, Pro plans).
  • Managing billing, invoices, and customer portals.
  • Webhooks from Stripe update the application's database with subscription status changes.

Data Flow & Core Interactions

The typical data flow within gh.gg starts with a user interaction on a Client Component. This component makes a request to the tRPC API Layer, which then routes the request to the appropriate backend procedure.

• Frontend Request: A user clicks to "Generate Scorecard" for a repository.
• tRPC Call: The client component makes a type-safe trpc.scorecard.generateScorecard.mutate() call.
• API Route/Backend Procedure: This procedure fetches necessary repository files via the GitHub API. It then sends relevant code snippets to Google Gemini AI for analysis.
• AI Processing: Gemini processes the code and returns structured analysis data.
• Database Storage: The analysis results are stored in the PostgreSQL database via Drizzle ORM. Token usage is also logged for billing.
• Response to Frontend: The tRPC procedure returns the analysis to the client, which then renders it in the UI.

In addition to user-initiated requests, gh.gg leverages GitHub Webhooks for automated workflows. When events like a new pull request or a push to a repository occur, GitHub sends a webhook payload to a dedicated API route. This route processes the event, triggers AI analysis (e.g., a PR code review), and uses the GitHub API to post a comment directly back on the pull request.

This architecture ensures a powerful, efficient, and intelligent experience for developers and teams using gh.gg.