Building an Intelligent Data Layer: Gemini API × GraphQL Architecture Guide

input UserQueryInput {
  query: String!
  context: String
  maxTokens: Int
}
 
type UserQueryResult {
  id: ID!
  originalQuery: String!
  aiGeneratedResponse: String!
  confidence: Float!
  sources: [Source!]!
  generatedAt: DateTime!
}
 
type Query {
  askAboutUser(input: UserQueryInput!): UserQueryResult!
}

union AiResponse = SuccessResponse | ErrorResponse | FallbackResponse
 
type SuccessResponse {
  content: String!
  confidence: Float!
}
 
type ErrorResponse {
  message: String!
  code: String!
  retryable: Boolean!
}
 
type FallbackResponse {
  cachedContent: String!
  isStale: Boolean!
}
 
type Query {
  generateContent(prompt: String!): AiResponse!
}

type ResolverContext = {
  geminiClient: GeminiClient;
  semanticCache: SemanticCache;
  dataLoader: DataLoader;
  userId: string;
  logger: Logger;
};
 
type AiResolver<T> = (
  parent: any,
  args: any,
  context: ResolverContext,
  info: GraphQLResolveInfo
) => Promise<T>;

const resolvers = {
  Query: {
    generateSummary: async (
      _: any,
      args: { text: string; language: string },
      context: ResolverContext
    ): Promise<SummaryResult> => {
      const { geminiClient, logger } = context;
 
      try {
        logger.info("Summary generation started", {
          textLength: args.text.length,
          language: args.language,
        });
 
        const response = await geminiClient.generateContent({
          contents: [
            {
              role: "user",
              parts: [
                {
                  text: `Summarize the following text in ${args.language}:\n\n${args.text}`,
                },
              ],
            },
          ],
          generationConfig: {
            maxOutputTokens: 256,
            temperature: 0.7,
          },
        });
 
        const summary =
          response.candidates[0]?.content?.parts[0]?.text || "";
 
        return {
          id: generateId(),
          originalText: args.text.substring(0, 200),
          summary,
          language: args.language,
          generatedAt: new Date(),
          tokensUsed: response.usageMetadata?.outputTokens || 0,
        };
      } catch (error) {
        logger.error("Summary generation failed", { error });
        throw new Error("Failed to generate summary");
      }
    },
  },
};

const resolvers = {
  Query: {
    analyzeProductReview: async (
      _: any,
      args: { reviewId: string },
      context: ResolverContext
    ): Promise<ReviewAnalysis> => {
      const { geminiClient, dataLoader, logger } = context;
 
      // Step 1: Fetch review text
      const review = await dataLoader.loadReview(args.reviewId);
 
      // Step 2: Call Gemini for sentiment, key points, and suggestions
      const analysisPrompt = `
Analyze this review and provide:
1. Sentiment score (-1 to 1)
2. Key criticisms (list format)
3. Suggested improvements
 
Review:
"${review.text}"
 
Return as JSON.
`;
 
      const response = await geminiClient.generateContent({
        contents: [
          { role: "user", parts: [{ text: analysisPrompt }] },
        ],
        generationConfig: {
          temperature: 0.3,
          maxOutputTokens: 512,
          responseMimeType: "application/json",
        },
      });
 
      const analysisText =
        response.candidates[0]?.content?.parts[0]?.text || "{}";
      const analysis = JSON.parse(analysisText);
 
      return {
        reviewId: args.reviewId,
        sentimentScore: analysis.sentimentScore,
        keyPoints: analysis.keyPoints,
        suggestions: analysis.suggestions,
        analyzedAt: new Date(),
      };
    },
  },
};

const resolvers = {
  Subscription: {
    generateDetailedGuide: {
      subscribe: async function* (
        _: any,
        args: { topic: string; depth: string },
        context: ResolverContext
      ) {
        const { geminiClient, logger } = context;
 
        logger.info("Guide generation stream started", {
          topic: args.topic,
          depth: args.depth,
        });
 
        const stream = geminiClient.generateContentStream({
          contents: [
            {
              role: "user",
              parts: [
                {
                  text: `Create a ${args.depth}-level guide about ${args.topic}. Structure it with clear section headings (##).`,
                },
              ],
            },
          ],
          generationConfig: {
            maxOutputTokens: 2048,
            temperature: 0.8,
          },
        });
 
        let buffer = "";
 
        for await (const chunk of stream) {
          const text = chunk.candidates[0]?.content?.parts[0]?.text || "";
          buffer += text;
 
          // Yield complete sections
          if (buffer.includes("##")) {
            const [section, ...rest] = buffer.split("##");
            yield {
              guideChunk: section.trim(),
              isComplete: false,
              timestamp: new Date(),
            };
            buffer = rest.join("##");
          }
        }
 
        if (buffer.trim()) {
          yield {
            guideChunk: buffer.trim(),
            isComplete: true,
            timestamp: new Date(),
          };
        }
      },
    },
  },
};

type CacheEntry = {
  key: string;
  embedding: number[]; // Generated via Gemini Embeddings API
  result: any;
  ttl: number;
  createdAt: Date;
};
 
class SemanticCache {
  private cache: Map<string, CacheEntry> = new Map();
  private embeddingClient: GeminiEmbedding;
  private similarityThreshold = 0.85;
 
  async get<T>(query: string): Promise<T | null> {
    // Embed the incoming query
    const queryEmbedding = await this.embeddingClient.embedContent({
      content: { parts: [{ text: query }] },
    });
 
    const queryVector = queryEmbedding.embedding.values;
    let bestMatch: CacheEntry | null = null;
    let bestSimilarity = 0;
 
    // Find highest-similarity cached entry
    for (const entry of this.cache.values()) {
      if (Date.now() - entry.createdAt.getTime() > entry.ttl) {
        this.cache.delete(entry.key);
        continue;
      }
 
      const similarity = this.cosineSimilarity(
        queryVector,
        entry.embedding
      );
 
      if (similarity > bestSimilarity && similarity >= this.similarityThreshold) {
        bestSimilarity = similarity;
        bestMatch = entry;
      }
    }
 
    if (bestMatch) {
      console.log(`Cache hit: similarity=${bestSimilarity.toFixed(3)}`);
      return bestMatch.result as T;
    }
 
    return null;
  }
 
  async set<T>(query: string, result: T, ttlMs: number = 3600000): Promise<void> {
    const embedding = await this.embeddingClient.embedContent({
      content: { parts: [{ text: query }] },
    });
 
    const key = `cache:${Date.now()}:${Math.random()}`;
    this.cache.set(key, {
      key,
      embedding: embedding.embedding.values,
      result,
      ttl: ttlMs,
      createdAt: new Date(),
    });
  }
 
  private cosineSimilarity(vecA: number[], vecB: number[]): number {
    const dotProduct = vecA.reduce((sum, a, i) => sum + a * vecB[i], 0);
    const magnitudeA = Math.sqrt(vecA.reduce((sum, a) => sum + a * a, 0));
    const magnitudeB = Math.sqrt(vecB.reduce((sum, b) => sum + b * b, 0));
    return dotProduct / (magnitudeA * magnitudeB);
  }
}

const resolvers = {
  Query: {
    generateSummary: async (
      _: any,
      args: { text: string },
      context: ResolverContext
    ) => {
      const { geminiClient, semanticCache, logger } = context;
 
      // Check semantic cache first
      const cached = await semanticCache.get<SummaryResult>(args.text);
      if (cached) {
        logger.info("Summary returned from semantic cache");
        return cached;
      }
 
      // Cache miss → API call
      const response = await geminiClient.generateContent({
        contents: [
          {
            role: "user",
            parts: [{ text: `Summarize: ${args.text}` }],
          },
        ],
      });
 
      const result = {
        id: generateId(),
        summary: response.candidates[0]?.content?.parts[0]?.text || "",
        generatedAt: new Date(),
      };
 
      // Store with 1-hour TTL
      await semanticCache.set(args.text, result, 3600000);
 
      return result;
    },
  },
};

const typeDefs = gql`
  type Subscription {
    generateArticleWithStreaming(topic: String!, length: String!): ArticleChunk!
  }
 
  type ArticleChunk {
    content: String!
    sectionTitle: String
    progress: Int! # 0-100
    isComplete: Boolean!
    estimatedTotalTokens: Int
  }
`;
 
const resolvers = {
  Subscription: {
    generateArticleWithStreaming: {
      subscribe: async function* (
        _: any,
        args: { topic: string; length: string },
        context: ResolverContext
      ) {
        const { geminiClient, logger } = context;
 
        const stream = geminiClient.generateContentStream({
          contents: [
            {
              role: "user",
              parts: [
                {
                  text: `Write a ${args.length} article about "${args.topic}". Use clear section headings (##).`,
                },
              ],
            },
          ],
          generationConfig: {
            maxOutputTokens: 3000,
            temperature: 0.7,
          },
        });
 
        let totalChars = 0;
 
        for await (const response of stream) {
          const text = response.candidates[0]?.content?.parts[0]?.text || "";
          totalChars += text.length;
 
          // Extract current section title
          const sectionMatches = text.match(/##\s+([^\n]+)/g) || [];
          const currentSectionTitle = sectionMatches[sectionMatches.length - 1]
            ?.replace(/^##\s+/, "")
            .trim();
 
          const progress = Math.min(
            Math.floor((totalChars / 5000) * 100),
            99
          );
 
          yield {
            content: text,
            sectionTitle: currentSectionTitle,
            progress,
            isComplete: false,
            estimatedTotalTokens: Math.floor(totalChars / 4),
          };
        }
 
        yield {
          content: "",
          sectionTitle: null,
          progress: 100,
          isComplete: true,
          estimatedTotalTokens: Math.floor(totalChars / 4),
        };
      },
    },
  },
};

// Subscription definition
const GENERATE_ARTICLE = gql`
  subscription GenerateArticleWithStreaming(
    $topic: String!
    $length: String!
  ) {
    generateArticleWithStreaming(topic: $topic, length: $length) {
      content
      sectionTitle
      progress
      isComplete
      estimatedTotalTokens
    }
  }
`;
 
// React component
function ArticleGenerator() {
  const [content, setContent] = useState("");
  const [progress, setProgress] = useState(0);
 
  const { loading, error } = useSubscription(GENERATE_ARTICLE, {
    variables: { topic: "GraphQL", length: "medium" },
    onData: ({ data }) => {
      const chunk = data.data.generateArticleWithStreaming;
      setContent((prev) => prev + chunk.content);
      setProgress(chunk.progress);
    },
  });
 
  return (
    <div>
      <progress value={progress} max={100} />
      <article>{content}</article>
    </div>
  );
}

{
  users {
    id
    name
    recommendations {  # One Gemini API call per user = N+1
      title
    }
  }
}

import DataLoader from "dataloader";
 
// Batch load recommendations for multiple users in one call
const recommendationBatchLoader = new DataLoader(
  async (userIds: string[]) => {
    console.log(`Batch loading recommendations for ${userIds.length} users`);
 
    // Single Gemini call for all users
    const response = await geminiClient.generateContent({
      contents: [
        {
          role: "user",
          parts: [
            {
              text: `Generate personalized article recommendations for users: ${userIds.join(", ")}.
              Return JSON: [{ userId, recommendations: [{ title, reason }] }]`,
            },
          ],
        },
      ],
      generationConfig: {
        responseMimeType: "application/json",
        temperature: 0.5,
      },
    });
 
    const results = JSON.parse(
      response.candidates[0]?.content?.parts[0]?.text || "[]"
    );
 
    // Return results in request order
    return userIds.map((id) =>
      results.find((r: any) => r.userId === id)?.recommendations || []
    );
  },
  {
    batchScheduleFn: (callback) => {
      // 10ms batching window
      setTimeout(callback, 10);
    },
  }
);
 
const resolvers = {
  User: {
    recommendations: async (parent: any, _: any, context: ResolverContext) => {
      return context.dataLoader.load(parent.id);
    },
  },
};
 
// Attach to context
const context = (req: any) => ({
  dataLoader: recommendationBatchLoader,
  geminiClient,
  // ...
});

import { verify } from "jsonwebtoken";
 
type AuthContext = {
  userId: string | null;
  userRole: "free" | "pro" | "admin";
  subscriptionTier: "free" | "basic" | "premium";
};
 
function authenticateToken(token: string | undefined): AuthContext {
  if (!token) {
    return {
      userId: null,
      userRole: "free",
      subscriptionTier: "free",
    };
  }
 
  try {
    const decoded = verify(token, process.env.JWT_SECRET!);
    return {
      userId: (decoded as any).userId,
      userRole: (decoded as any).role,
      subscriptionTier: (decoded as any).tier,
    };
  } catch {
    return {
      userId: null,
      userRole: "free",
      subscriptionTier: "free",
    };
  }
}

type RateLimitConfig = {
  free: { requestsPerDay: number; tokensPerDay: number };
  basic: { requestsPerDay: number; tokensPerDay: number };
  premium: { requestsPerDay: number; tokensPerDay: number };
};
 
const RATE_LIMITS: RateLimitConfig = {
  free: { requestsPerDay: 10, tokensPerDay: 5000 },
  basic: { requestsPerDay: 100, tokensPerDay: 50000 },
  premium: { requestsPerDay: 1000, tokensPerDay: 500000 },
};
 
class RateLimiter {
  private redis: RedisClient;
 
  async checkLimit(userId: string, tier: string, tokensUsed: number): Promise<{
    allowed: boolean;
    remaining: number;
  }> {
    const key = `ratelimit:${userId}:${new Date().toDateString()}`;
    const config = RATE_LIMITS[tier as keyof RateLimitConfig] || RATE_LIMITS.free;
 
    const current = await this.redis.get(key);
    const currentTokens = current ? JSON.parse(current) : { tokens: 0, requests: 0 };
 
    const newTokenCount = currentTokens.tokens + tokensUsed;
    const newRequestCount = currentTokens.requests + 1;
 
    if (
      newTokenCount > config.tokensPerDay ||
      newRequestCount > config.requestsPerDay
    ) {
      return { allowed: false, remaining: config.tokensPerDay - newTokenCount };
    }
 
    await this.redis.setex(
      key,
      86400,
      JSON.stringify({
        tokens: newTokenCount,
        requests: newRequestCount,
      })
    );
 
    return {
      allowed: true,
      remaining: config.tokensPerDay - newTokenCount,
    };
  }
}
 
// In resolvers
const resolvers = {
  Query: {
    generateContent: async (
      _: any,
      args: any,
      context: ResolverContext & { auth: AuthContext }
    ) => {
      if (context.auth.subscriptionTier === "free") {
        throw new Error("This feature requires a subscription");
      }
 
      const { allowed } = await rateLimiter.checkLimit(
        context.auth.userId!,
        context.auth.subscriptionTier,
        0
      );
 
      if (!allowed) {
        throw new Error("Rate limit exceeded");
      }
 
      // Proceed with generation...
    },
  },
};

class MockGeminiClient {
  private responses: Map<string, string> = new Map();
 
  setMockResponse(prompt: string, response: string) {
    this.responses.set(prompt, response);
  }
 
  async generateContent(config: any): Promise<any> {
    const prompt = config.contents[0]?.parts[0]?.text || "";
    const mockResponse = this.responses.get(prompt);
 
    if (!mockResponse) {
      throw new Error(`No mock response for prompt: ${prompt}`);
    }
 
    return {
      candidates: [
        {
          content: {
            parts: [{ text: mockResponse }],
          },
        },
      ],
      usageMetadata: {
        inputTokens: 10,
        outputTokens: mockResponse.split(" ").length,
      },
    };
  }
 
  async generateContentStream(config: any) {
    const response = await this.generateContent(config);
    const text = response.candidates[0].content.parts[0].text;
 
    async function* generator() {
      const chunks = text.split(" ");
      for (const chunk of chunks) {
        yield response;
      }
    }
 
    return generator();
  }
}

describe("generateSummary resolver", () => {
  let mockGeminiClient: MockGeminiClient;
  let context: ResolverContext;
 
  beforeEach(() => {
    mockGeminiClient = new MockGeminiClient();
    context = {
      geminiClient: mockGeminiClient as any,
      semanticCache: new Map(),
      dataLoader: new DataLoader(async (ids) => ids),
      userId: "test-user",
      logger: console,
    };
  });
 
  it("should generate summary correctly", async () => {
    const testText = "This is a long text about GraphQL and AI integration.";
    const expectedSummary = "Summary about GraphQL and AI";
 
    mockGeminiClient.setMockResponse(testText, expectedSummary);
 
    const result = await resolvers.Query.generateSummary(
      null,
      { text: testText },
      context
    );
 
    expect(result.summary).toBe(expectedSummary);
  });
 
  it("should leverage semantic cache for similar queries", async () => {
    const text1 = "GraphQL is a query language";
    const text2 = "GraphQL: a query language"; // Similar content
 
    mockGeminiClient.setMockResponse(text1, "GraphQL summary");
 
    // First call triggers API
    const result1 = await resolvers.Query.generateSummary(
      null,
      { text: text1 },
      context
    );
 
    // Second call should hit semantic cache (verify via logging)
  });
});

// budget carried on the per-request context
interface AIBudget {
  remaining: number;
  spent: number;
}
 
export function createAIBudget(max = 25): AIBudget {
  return { remaining: max, spent: 0 };
}
 
// every AI-backed resolver must go through this wrapper
export async function withAIBudget<T>(
  budget: AIBudget,
  fn: () => Promise<T>,
): Promise<T> {
  if (budget.remaining <= 0) {
    throw new GraphQLError(
      `AI call budget exceeded for this request (max ${budget.spent} calls).`,
      { extensions: { code: "AI_BUDGET_EXCEEDED" } },
    );
  }
  budget.remaining -= 1;
  budget.spent += 1;
  return fn();
}

const resolvers = {
  User: {
    aiSummary: (parent, _args, ctx) =>
      withAIBudget(ctx.aiBudget, () => geminiSummarize(parent.bio)),
  },
};

// estimate AI calls from the query AST before execution (heuristic)
import { parse, visit } from "graphql";
 
const AI_FIELDS = new Set(["aiSummary", "semanticSearch", "aiTranslate"]);
 
function estimateAICalls(query: string, defaultListSize = 50): number {
  const ast = parse(query);
  let multiplier = 1;
  let aiCalls = 0;
 
  visit(ast, {
    Field: {
      enter(node) {
        const first = node.arguments?.find((a) => a.name.value === "first");
        if (first && first.value.kind === "IntValue") {
          multiplier *= Number(first.value.value);
        }
        if (AI_FIELDS.has(node.name.value)) aiCalls += multiplier;
      },
      leave(node) {
        const first = node.arguments?.find((a) => a.name.value === "first");
        if (first && first.value.kind === "IntValue") {
          multiplier /= Number(first.value.value);
        }
      },
    },
  });
 
  return aiCalls;
}
 
const MAX_ESTIMATED_AI_CALLS = 25;
 
export function guardQueryCost(query: string): void {
  const estimate = estimateAICalls(query);
  if (estimate > MAX_ESTIMATED_AI_CALLS) {
    throw new GraphQLError(
      `This query would trigger ~${estimate} AI calls (limit ${MAX_ESTIMATED_AI_CALLS}). Reduce list sizes or split the query.`,
      { extensions: { code: "QUERY_TOO_EXPENSIVE" } },
    );
  }
}

import { tracer } from "@opentelemetry/api";
import winston from "winston";
 
const logger = winston.createLogger({
  format: winston.format.json(),
  transports: [new winston.transports.Console()],
});
 
const resolvers = {
  Query: {
    generateContent: async (
      _: any,
      args: any,
      context: ResolverContext
    ) => {
      const span = tracer.startSpan("generateContent");
 
      try {
        span.setAttributes({
          userId: context.userId,
          promptLength: args.prompt.length,
        });
 
        logger.info("Starting content generation", {
          userId: context.userId,
          promptLength: args.prompt.length,
          timestamp: new Date().toISOString(),
        });
 
        const startTime = Date.now();
        const response = await context.geminiClient.generateContent({
          contents: [{ role: "user", parts: [{ text: args.prompt }] }],
        });
 
        const duration = Date.now() - startTime;
 
        logger.info("Content generation completed", {
          userId: context.userId,
          duration,
          outputTokens: response.usageMetadata?.outputTokens,
        });
 
        span.addEvent("generation_completed", {
          duration,
          tokensUsed: response.usageMetadata?.outputTokens,
        });
 
        return {
          id: generateId(),
          content: response.candidates[0]?.content?.parts[0]?.text || "",
          generatedAt: new Date(),
        };
      } catch (error) {
        logger.error("Content generation failed", {
          userId: context.userId,
          error: (error as Error).message,
        });
 
        span.recordException(error as Error);
        span.setStatus({ code: 2 });
        throw error;
      } finally {
        span.end();
      }
    },
  },
};

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3,
  initialDelayMs: number = 1000
): Promise<T> {
  let lastError: Error | null = null;
 
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;
 
      // Check if error is retryable
      const isRetryable =
        (error as any).status === 429 || // Rate limit
        (error as any).status === 503 || // Service unavailable
        (error as any).code === "ECONNRESET";
 
      if (!isRetryable || attempt === maxRetries) {
        throw error;
      }
 
      // Exponential backoff
      const delayMs = initialDelayMs * Math.pow(2, attempt - 1);
      logger.warn(`Retry attempt ${attempt}/${maxRetries} after ${delayMs}ms`, {
        error: (error as Error).message,
      });
 
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
  }
 
  throw lastError;
}
 
// Use in resolver
const response = await withRetry(
  () =>
    context.geminiClient.generateContent({
      contents: [{ role: "user", parts: [{ text: args.prompt }] }],
    }),
  3,
  1000
);

class MetricsCollector {
  private metrics = {
    totalRequests: 0,
    successfulRequests: 0,
    failedRequests: 0,
    totalTokensUsed: 0,
    averageResponseTime: 0,
  };
 
  recordRequest(success: boolean, tokensUsed: number, responseTime: number) {
    this.metrics.totalRequests++;
 
    if (success) {
      this.metrics.successfulRequests++;
    } else {
      this.metrics.failedRequests++;
    }
 
    this.metrics.totalTokensUsed += tokensUsed;
    this.metrics.averageResponseTime =
      (this.metrics.averageResponseTime * (this.metrics.totalRequests - 1) +
        responseTime) /
      this.metrics.totalRequests;
  }
 
  getMetrics() {
    return {
      ...this.metrics,
      successRate: this.metrics.successfulRequests / this.metrics.totalRequests,
    };
  }
 
  exportPrometheus(): string {
    return `
# HELP graphql_ai_requests_total Total number of AI-powered requests
# TYPE graphql_ai_requests_total counter
graphql_ai_requests_total{status="success"} ${this.metrics.successfulRequests}
graphql_ai_requests_total{status="failure"} ${this.metrics.failedRequests}
 
# HELP graphql_ai_tokens_total Total tokens consumed
# TYPE graphql_ai_tokens_total counter
graphql_ai_tokens_total ${this.metrics.totalTokensUsed}
 
# HELP graphql_ai_response_time_ms Average response time in milliseconds
# TYPE graphql_ai_response_time_ms gauge
graphql_ai_response_time_ms ${Math.round(this.metrics.averageResponseTime)}
    `;
  }
}