💳 Payment & Billing (Stripe)

The gh.gg platform integrates with Stripe to manage user subscriptions, enabling access to advanced AI features and private repository analysis. This system ensures secure payment processing, flexible plan management, and accurate tracking of AI resource consumption. As part of the broader Architecture Overview, Stripe plays a vital role in the monetization layer of gh.gg.

Subscription Plans

gh.gg offers two primary paid subscription plans:

1. Developer (BYOK - Bring Your Own Key): This plan grants users access to private repositories and advanced AI features, with the user providing their own Google Gemini API key. This model allows for virtually unlimited AI usage, as the costs are managed directly by the user with Google.
2. Pro: This plan includes access to private repositories and a generous monthly quota of managed AI tokens, with an option to also use a BYOK. This is ideal for users who prefer a simpler, all-inclusive billing model.

The Free plan provides basic analysis of public repositories without AI features.

Database Integration: userSubscriptions and userApiKeys

The core of the billing system's data persistence lies within two key tables in the Database Schema & ORM (src/db/schema.ts):

• userSubscriptions: This table stores the active subscription details for each user.

  • userId: Foreign key linking to the user table.
  • stripeCustomerId: The unique identifier for the customer in Stripe.
  • stripeSubscriptionId: The unique identifier for the subscription in Stripe.
  • plan: Indicates the user's current plan (byok or pro).
  • status: Reflects the subscription status (e.g., active, canceled, past_due).
  • currentPeriodEnd: The date when the current billing period ends, used to determine if a subscription is active.

• userApiKeys: This table securely stores the encrypted Gemini API keys for users who opt for the "Bring Your Own Key" (BYOK) plan.

  • userId: Foreign key linking to the user table.
  • encryptedGeminiApiKey: The user's Google Gemini API key, stored in an encrypted format using src/lib/utils/encryption.ts. This ensures that raw API keys are never stored in plain text.

These tables are crucial for determining a user's access level to features and whether to use a managed AI budget or their own provided API key.

Creating Checkout Sessions

When a user decides to upgrade their plan, they initiate a checkout session via the trpc.billing.createCheckoutSession procedure (src/lib/trpc/routes/billing.ts). The process typically involves:

1. Client-Side Request: The user selects a plan (e.g., "Developer" or "Pro") from the pricing page.
2. tRPC Mutation: A call is made to trpc.billing.createCheckoutSession.mutate() with the selected plan.
3. Stripe Checkout: The backend (via tRPC) communicates with the Stripe API to create a new checkout session. Stripe generates a unique URL for this session.
4. Redirection: The user's browser is redirected to the Stripe-hosted checkout page, where they can securely enter their payment information.

Upon successful completion of the checkout process, Stripe handles the creation of the customer and subscription.

Webhook Handling for Subscription Updates

To keep the gh.gg database synchronized with Stripe's subscription status, a dedicated Stripe webhook handler is implemented at /api/webhooks/stripe. This handler listens for critical events from Stripe:

• checkout.session.completed: When a user successfully completes a checkout session, this event is triggered. The webhook handler creates or updates an entry in the userSubscriptions table, marking the user's plan as active and storing their stripeCustomerId and stripeSubscriptionId.
• customer.subscription.updated: Any changes to a subscription (e.g., plan changes, renewal, payment issues) trigger this event. The webhook updates the status, plan, and currentPeriodEnd fields in the userSubscriptions table.
• customer.subscription.deleted: When a subscription is canceled or ends, this event is received. The webhook marks the status of the subscription as canceled in the database.

This asynchronous webhook-driven approach ensures that the application's internal state accurately reflects the user's subscription status without relying on polling or complex direct API calls from the frontend.

API Key Management (BYOK)

For users on the "Developer (BYOK)" plan, the platform allows them to store their own Google Gemini API key:

• Secure Storage: Users can input their Gemini API key via the settings page. This key is immediately encrypted using src/lib/utils/encryption.ts and stored in the userApiKeys table.
• Decryption on Demand: When AI features are invoked by a BYOK user, the encrypted key is retrieved from the database, decrypted in memory (using decryptApiKey), and then used to authenticate with the Google Gemini AI API.
• Usage Logic: The src/lib/utils/user-plan.ts module centralizes the logic for determining a user's current plan and retrieving the appropriate API key (either their BYOK key or the platform's managed key for Pro users).

Token Usage Tracking

The tokenUsage table (src/db/schema.ts) tracks every AI request made by a user, including:

• userId: The user who initiated the request.
• feature: The specific AI feature used (e.g., diagram, scorecard, pr_review).
• inputTokens, outputTokens, totalTokens: The number of tokens consumed.
• isByok: A boolean indicating if the request used the user's own API key or a managed one.

This granular tracking, along with the logic in src/lib/utils/cost-calculator.ts, allows the platform to monitor AI costs, manage usage quotas for Pro plan users, and provide transparency in billing.

The combination of Stripe for flexible billing, secure API key management, and robust token usage tracking provides a comprehensive and scalable payment and billing system for gh.gg.