[10.1] Gemini Configuration

1. Front Matter

• Title: Gemini Configuration

• Author: scorevi

• Reviewers: Joshua-Yel

• Created: February 2026

• Status: Approved

• References:

  • Issue: [10.1] Gemini Configuration #67

  • Milestone: [10] System Config

2. Introduction & Goals

• Problem Summary: Super Admins need a secure panel to manage Google Gemini API credentials and model settings across all AI features, with masked API key display and live connection testing.

• Goals:

  • Secure API key management with masking

  • Model selection from available Gemini models

  • Live connection testing before save

  • Per-model pricing configuration

• Non-Goals:

  • Multi-tenant API key management

  • Automatic key rotation

  • Cost allocation per user

• Glossary:

  • Masked Input: API key display showing only first 4 + last 4 chars

  • Temperature: AI response randomness (0.0-1.0)

3. High-Level Architecture

• System Diagram:

• Technologies Used:

  • Google Gemini SDK - AI model access

  • Supabase - Config storage

  • React Hook Form - Form management

  • Zod - Schema validation

4. Detailed Design & Implementation

• Data Model / Schema:

  gemini_config Table:

  Column	Type	Description
  id	UUID PK	Auto-generated
  api_key	TEXT	Encrypted API key
  model_name	TEXT	Selected Gemini model
  temperature	FLOAT	0.0-1.0, default 0.7
  is_active	BOOLEAN	Only one active config
  created_at	TIMESTAMPTZ	Creation time
  updated_at	TIMESTAMPTZ	Auto-updated

  gemini_pricing Table:

  Column	Type	Description
  model_name	TEXT PK	Gemini model identifier
  input_cost	NUMERIC	Cost per 1K input tokens
  output_cost	NUMERIC	Cost per 1K output tokens

• API Specification:

  • GET /api/admin/gemini/api-key - Fetch current config (masked)

  • PUT /api/admin/gemini/api-key - Update configuration

  • POST /api/admin/gemini/test - Test connection

• Logic & Workflows:

  Available Models:

  • gemini-3.1-pro-preview - Premium, highest quality

  • gemini-3-flash-preview - Fast & cost-effective (recommended)

  • gemini-2.5-pro - Stable, advanced reasoning

  • gemini-2.5-flash - Stable, fast, low cost

  API Key Masking:

  1. Display: First 4 + last 4 chars, rest •••••

  2. Eye toggle to reveal/hide

  3. Must reveal before save (prevents masked string corruption)

  4. Validation: Minimum 20 characters

• Key Files:

  • components/admin/GeminiConfigForm.tsx - Config form UI

  • lib/api/admin/gemini-config.server-action.ts - CRUD operations

  • lib/ai/api-key-manager.ts - Key encryption

  • lib/ai/model-config.service.ts - Model selection

5. Infrastructure & Operations

• Dependencies:

  • Google Gemini API - AI model access

  • Supabase - Config persistence

• Monitoring & Alerting:

  • Test Connection: Validates API key + model before save

  • Logging: Track config changes for audit

• Deployment Plan:

  1. Run gemini_config migration

  2. Run gemini_pricing migration

  3. Deploy admin UI

  4. Set initial API key via admin panel

6. Testing & Quality Assurance

• Test Strategy:

  • Manual: Key masking, test connection

  • Integration: Config save, model switching

• Known Limitations:

  • Single active config (no multi-tenant)

  • No automatic key rotation

  • API key stored encrypted but not hashed

7. Maintenance & Support

• Troubleshooting:

  • "Invalid API key" → Verify key in Google Cloud Console

  • Test connection timeout → Check network, Gemini API status

  • Masked key saved → Must reveal before save

• Changelog:

  • 1.0 (Feb 2026): Initial implementation

  • 1.1 (Feb 2026): Added pricing table

Document Version

1.1 - Approved, Feature deployed to production, 03/01/2026