more refactoring oops

netlify/functions/batch-follow-users.ts

···
-import { AuthenticatedHandler } from "./shared/types";
-import { SessionService } from "./shared/services/session";
-import { MatchRepository } from "./shared/repositories";
-import { successResponse } from "./shared/utils";
-import { withAuthErrorHandling } from "./shared/middleware";
-import { ValidationError } from "./shared/constants/errors";
+import { AuthenticatedHandler } from "./core/types";
+import { SessionService } from "./services/SessionService";
+import { FollowService } from "./services/FollowService";
+import { MatchRepository } from "./repositories";
+import { successResponse } from "./utils";
+import { withAuthErrorHandling } from "./core/middleware";
+import { ValidationError } from "./core/errors";
 
 const batchFollowHandler: AuthenticatedHandler = async (context) => {
-  // Parse request body
   const body = JSON.parse(context.event.body || "{}");
   const dids: string[] = body.dids || [];
   const followLexicon: string = body.followLexicon || "app.bsky.graph.follow";
···
     throw new ValidationError("dids array is required and must not be empty");
   }
 
-  // Limit batch size to prevent timeouts and respect rate limits
   if (dids.length > 100) {
     throw new ValidationError("Maximum 100 DIDs per batch");
   }
 
-  // Get authenticated agent using SessionService
-  const { agent } = await SessionService.getAgentForSession(context.sessionId);
-
-  // Check existing follows before attempting to follow
-  const alreadyFollowing = new Set<string>();
-  try {
-    let cursor: string | undefined = undefined;
-    let hasMore = true;
-    const didsSet = new Set(dids);
-
-    while (hasMore && didsSet.size > 0) {
-      const response = await agent.api.com.atproto.repo.listRecords({
-        repo: context.did,
-        collection: followLexicon,
-        limit: 100,
-        cursor,
-      });
-
-      for (const record of response.data.records) {
-        const followRecord = record.value as any;
-        if (followRecord?.subject && didsSet.has(followRecord.subject)) {
-          alreadyFollowing.add(followRecord.subject);
-          didsSet.delete(followRecord.subject);
-        }
-      }
+  const { agent } = await SessionService.getAgentForSession(
+    context.sessionId,
+    context.event,
+  );
 
-      cursor = response.data.cursor;
-      hasMore = !!cursor;
-
-      if (didsSet.size === 0) {
-        break;
-      }
-    }
-  } catch (error) {
-    console.error("Error checking existing follows:", error);
-    // Continue - we'll handle duplicates in the follow loop
-  }
+  const alreadyFollowing = await FollowService.getAlreadyFollowing(
+    agent,
+    context.did,
+    dids,
+    followLexicon,
+  );
 
-  // Follow all users
   const results = [];
   let consecutiveErrors = 0;
   const MAX_CONSECUTIVE_ERRORS = 3;
   const matchRepo = new MatchRepository();
 
   for (const did of dids) {
-    // Skip if already following
     if (alreadyFollowing.has(did)) {
       results.push({
         did,
···
         error: null,
       });
 
-      // Update database follow status
       try {
         await matchRepo.updateFollowStatus(did, followLexicon, true);
       } catch (dbError) {
···
         error: null,
       });
 
-      // Update database follow status
       try {
         await matchRepo.updateFollowStatus(did, followLexicon, true);
       } catch (dbError) {
         console.error("Failed to update follow status in DB:", dbError);
       }
 
-      // Reset error counter on success
       consecutiveErrors = 0;
     } catch (error) {
       consecutiveErrors++;
···
         error: error instanceof Error ? error.message : "Follow failed",
       });
 
-      // If we hit rate limits, implement exponential backoff
       if (
         error instanceof Error &&
         (error.message.includes("rate limit") || error.message.includes("429"))
···
         console.log(`Rate limit hit. Backing off for ${backoffDelay}ms...`);
         await new Promise((resolve) => setTimeout(resolve, backoffDelay));
       } else if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
-        // For other repeated errors, small backoff
         await new Promise((resolve) => setTimeout(resolve, 500));
       }
     }

netlify/functions/batch-search-actors.ts

···
-import { AuthenticatedHandler } from "./shared/types";
-import { SessionService } from "./shared/services/session";
-import { successResponse } from "./shared/utils";
-import { withAuthErrorHandling } from "./shared/middleware";
-import { ValidationError } from "./shared/constants/errors";
-import { normalize } from "./shared/utils/string.utils";
+import { AuthenticatedHandler } from "./core/types";
+import { SessionService } from "./services/SessionService";
+import { successResponse } from "./utils";
+import { withAuthErrorHandling } from "./core/middleware";
+import { ValidationError } from "./core/errors";
+import { normalize } from "./utils/string.utils";
+import { FollowService } from "./services/FollowService";
 
 const batchSearchHandler: AuthenticatedHandler = async (context) => {
-  // Parse batch request
   const body = JSON.parse(context.event.body || "{}");
   const usernames: string[] = body.usernames || [];
 
···
     );
   }
 
-  // Limit batch size to prevent timeouts
   if (usernames.length > 50) {
     throw new ValidationError("Maximum 50 usernames per batch");
   }
 
-  // Get authenticated agent using SessionService
-  const { agent } = await SessionService.getAgentForSession(context.sessionId);
+  const { agent } = await SessionService.getAgentForSession(
+    context.sessionId,
+    context.event,
+  );
 
-  // Search all usernames in parallel
   const searchPromises = usernames.map(async (username) => {
     try {
       const response = await agent.app.bsky.actor.searchActors({
···
         limit: 20,
       });
 
-      // Filter and rank matches
       const normalizedUsername = normalize(username);
 
       const rankedActors = response.data.actors
···
 
   const results = await Promise.all(searchPromises);
 
-  // Enrich results with follower and post counts using getProfiles
   const allDids = results
     .flatMap((r) => r.actors.map((a: any) => a.did))
     .filter((did): did is string => !!did);
 
   if (allDids.length > 0) {
-    // Create a map to store enriched profile data
     const profileDataMap = new Map<
       string,
       { postCount: number; followerCount: number }
     >();
 
-    // Batch fetch profiles (25 at a time - API limit)
     const PROFILE_BATCH_SIZE = 25;
     for (let i = 0; i < allDids.length; i += PROFILE_BATCH_SIZE) {
       const batch = allDids.slice(i, i + PROFILE_BATCH_SIZE);
···
         });
       } catch (error) {
         console.error("Failed to fetch profile batch:", error);
-        // Continue even if one batch fails
       }
     }
 
-    // Merge enriched data back into results
     results.forEach((result) => {
       result.actors = result.actors.map((actor: any) => {
         const enrichedData = profileDataMap.get(actor.did);
···
     });
   }
 
-  // Check follow status for all matched DIDs in chosen lexicon
   const followLexicon = body.followLexicon || "app.bsky.graph.follow";
 
   if (allDids.length > 0) {
     try {
-      let cursor: string | undefined = undefined;
-      let hasMore = true;
-      const didsSet = new Set(allDids);
-      const followedDids = new Set<string>();
-
-      // Query user's follow graph
-      while (hasMore && didsSet.size > 0) {
-        const response = await agent.api.com.atproto.repo.listRecords({
-          repo: context.did,
-          collection: followLexicon,
-          limit: 100,
-          cursor,
-        });
-
-        // Check each record
-        for (const record of response.data.records) {
-          const followRecord = record.value as any;
-          if (followRecord?.subject && didsSet.has(followRecord.subject)) {
-            followedDids.add(followRecord.subject);
-          }
-        }
-
-        cursor = response.data.cursor;
-        hasMore = !!cursor;
-      }
+      const followStatus = await FollowService.checkFollowStatus(
+        agent,
+        context.did,
+        allDids,
+        followLexicon,
+      );
 
-      // Add follow status to results
       results.forEach((result) => {
         result.actors = result.actors.map((actor: any) => ({
           ...actor,
           followStatus: {
-            [followLexicon]: followedDids.has(actor.did),
+            [followLexicon]: followStatus[actor.did] || false,
           },
         }));
       });
     } catch (error) {
       console.error("Failed to check follow status during search:", error);
-      // Continue without follow status - non-critical
     }
   }
 

netlify/functions/check-follow-status.ts

···
-import { AuthenticatedHandler } from "./shared/types";
-import { SessionService } from "./shared/services/session";
-import { successResponse } from "./shared/utils";
-import { withAuthErrorHandling } from "./shared/middleware";
-import { ValidationError } from "./shared/constants/errors";
+import { AuthenticatedHandler } from "./core/types";
+import { SessionService } from "./services/SessionService";
+import { FollowService } from "./services/FollowService";
+import { successResponse } from "./utils";
+import { withAuthErrorHandling } from "./core/middleware";
+import { ValidationError } from "./core/errors";
 
 const checkFollowStatusHandler: AuthenticatedHandler = async (context) => {
-  // Parse request body
   const body = JSON.parse(context.event.body || "{}");
   const dids: string[] = body.dids || [];
   const followLexicon: string = body.followLexicon || "app.bsky.graph.follow";
···
     throw new ValidationError("dids array is required and must not be empty");
   }
 
-  // Limit batch size
   if (dids.length > 100) {
     throw new ValidationError("Maximum 100 DIDs per batch");
   }
 
-  // Get authenticated agent using SessionService
-  const { agent } = await SessionService.getAgentForSession(context.sessionId);
-
-  // Build follow status map
-  const followStatus: Record<string, boolean> = {};
-
-  // Initialize all as not following
-  dids.forEach((did) => {
-    followStatus[did] = false;
-  });
-
-  // Query user's follow graph for the specific lexicon
-  try {
-    let cursor: string | undefined = undefined;
-    let hasMore = true;
-    const didsSet = new Set(dids);
-
-    while (hasMore && didsSet.size > 0) {
-      const response = await agent.api.com.atproto.repo.listRecords({
-        repo: context.did,
-        collection: followLexicon,
-        limit: 100,
-        cursor,
-      });
-
-      // Check each record
-      for (const record of response.data.records) {
-        const followRecord = record.value as any;
-        if (followRecord?.subject && didsSet.has(followRecord.subject)) {
-          followStatus[followRecord.subject] = true;
-          didsSet.delete(followRecord.subject); // Found it, no need to keep checking
-        }
-      }
-
-      cursor = response.data.cursor;
-      hasMore = !!cursor;
+  const { agent } = await SessionService.getAgentForSession(
+    context.sessionId,
+    context.event,
+  );
 
-      // If we've found all DIDs, break early
-      if (didsSet.size === 0) {
-        break;
-      }
-    }
-  } catch (error) {
-    console.error("Error querying follow graph:", error);
-    // On error, return all as false (not following) - fail safe
-  }
+  const followStatus = await FollowService.checkFollowStatus(
+    agent,
+    context.did,
+    dids,
+    followLexicon,
+  );
 
   return successResponse({ followStatus });
 };

netlify/functions/core/errors/ApiError.ts

···
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number = 500,
+    public details?: string,
+  ) {
+    super(message);
+    this.name = "ApiError";
+    Object.setPrototypeOf(this, ApiError.prototype);
+  }
+}

netlify/functions/core/errors/AuthenticationError.ts

···
+import { ApiError } from "./ApiError";
+
+export class AuthenticationError extends ApiError {
+  constructor(message: string = "Authentication required", details?: string) {
+    super(message, 401, details);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, AuthenticationError.prototype);
+  }
+}

netlify/functions/core/errors/DatabaseError.ts

···
+import { ApiError } from "./ApiError";
+
+export class DatabaseError extends ApiError {
+  constructor(message: string = "Database operation failed", details?: string) {
+    super(message, 500, details);
+    this.name = "DatabaseError";
+    Object.setPrototypeOf(this, DatabaseError.prototype);
+  }
+}

netlify/functions/core/errors/NotFoundError.ts

···
+import { ApiError } from "./ApiError";
+
+export class NotFoundError extends ApiError {
+  constructor(message: string = "Resource not found", details?: string) {
+    super(message, 404, details);
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, NotFoundError.prototype);
+  }
+}

netlify/functions/core/errors/ValidationError.ts

···
+import { ApiError } from "./ApiError";
+
+export class ValidationError extends ApiError {
+  constructor(message: string, details?: string) {
+    super(message, 400, details);
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, ValidationError.prototype);
+  }
+}

netlify/functions/core/errors/index.ts

···
+export * from "./ApiError";
+export * from "./AuthenticationError";
+export * from "./ValidationError";
+export * from "./NotFoundError";
+export * from "./DatabaseError";
+
+export const ERROR_MESSAGES = {
+  NO_SESSION_COOKIE: "No session cookie",
+  INVALID_SESSION: "Invalid or expired session",
+  MISSING_PARAMETERS: "Missing required parameters",
+  OAUTH_FAILED: "OAuth authentication failed",
+  DATABASE_ERROR: "Database operation failed",
+  PROFILE_FETCH_FAILED: "Failed to fetch profile",
+  SEARCH_FAILED: "Search operation failed",
+  FOLLOW_FAILED: "Follow operation failed",
+  SAVE_FAILED: "Failed to save results",
+} as const;

netlify/functions/get-upload-details.ts

···
-import { AuthenticatedHandler } from "./shared/types";
-import { MatchRepository } from "./shared/repositories";
-import { successResponse } from "./shared/utils";
-import { withAuthErrorHandling } from "./shared/middleware";
-import { ValidationError, NotFoundError } from "./shared/constants/errors";
+import { AuthenticatedHandler } from "./core/types";
+import { MatchRepository } from "./repositories";
+import { successResponse } from "./utils";
+import { withAuthErrorHandling } from "./core/middleware";
+import { ValidationError, NotFoundError } from "./core/errors";
 
 const DEFAULT_PAGE_SIZE = 50;
 const MAX_PAGE_SIZE = 100;

netlify/functions/get-uploads.ts

···
-import { AuthenticatedHandler } from "./shared/types";
-import { UploadRepository } from "./shared/repositories";
-import { successResponse } from "./shared/utils";
-import { withAuthErrorHandling } from "./shared/middleware";
+import { AuthenticatedHandler } from "./core/types";
+import { UploadRepository } from "./repositories";
+import { successResponse } from "./utils";
+import { withAuthErrorHandling } from "./core/middleware";
 
 const getUploadsHandler: AuthenticatedHandler = async (context) => {
   const uploadRepo = new UploadRepository();
 
-  // Fetch all uploads for this user
   const uploads = await uploadRepo.getUserUploads(context.did);
 
   return successResponse({

netlify/functions/infrastructure/cache/CacheService.ts

···
+/**
+ * Generic in-memory cache with TTL support
+ * Used for both server-side caching (config, profiles) and client-side caching
+ **/
+export class CacheService<T = any> {
+  private cache = new Map<string, { value: T; expires: number }>();
+  private readonly defaultTTL: number;
+
+  constructor(defaultTTLMs: number = 5 * 60 * 1000) {
+    this.defaultTTL = defaultTTLMs;
+  }
+
+  set(key: string, value: T, ttlMs?: number): void {
+    const ttl = ttlMs ?? this.defaultTTL;
+    this.cache.set(key, {
+      value,
+      expires: Date.now() + ttl,
+    });
+
+    // Auto-cleanup if cache grows too large
+    if (this.cache.size > 100) {
+      this.cleanup();
+    }
+  }
+
+  get(key: string, ttlMs?: number): T | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+
+    const ttl = ttlMs ?? this.defaultTTL;
+    if (Date.now() - (entry.expires - ttl) > ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.value;
+  }
+
+  has(key: string): boolean {
+    return this.get(key) !== null;
+  }
+
+  delete(key: string): void {
+    this.cache.delete(key);
+  }
+
+  invalidatePattern(pattern: string): void {
+    for (const key of this.cache.keys()) {
+      if (key.includes(pattern)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expires) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  size(): number {
+    return this.cache.size;
+  }
+}
+
+// Singleton instances for common use cases
+export const configCache = new CacheService<any>(5 * 60 * 1000); // 5 min
+export const profileCache = new CacheService<any>(5 * 60 * 1000); // 5 min

netlify/functions/infrastructure/database/DatabaseConnection.ts

···
+import { neon, NeonQueryFunction } from "@neondatabase/serverless";
+import { DatabaseError } from "../../core/errors";
+
+/**
+ * Singleton Database Connection Manager
+ * Ensures single connection instance across all function invocations
+ **/
+class DatabaseConnection {
+  private static instance: DatabaseConnection;
+  private sql: NeonQueryFunction<any, any> | null = null;
+  private initialized = false;
+
+  private constructor() {}
+
+  static getInstance(): DatabaseConnection {
+    if (!DatabaseConnection.instance) {
+      DatabaseConnection.instance = new DatabaseConnection();
+    }
+    return DatabaseConnection.instance;
+  }
+
+  getClient(): NeonQueryFunction<any, any> {
+    if (!this.sql) {
+      this.initialize();
+    }
+    return this.sql!;
+  }
+
+  private initialize(): void {
+    if (this.initialized) return;
+
+    if (!process.env.NETLIFY_DATABASE_URL) {
+      throw new DatabaseError(
+        "Database connection string not configured",
+        "NETLIFY_DATABASE_URL environment variable is missing",
+      );
+    }
+
+    try {
+      this.sql = neon(process.env.NETLIFY_DATABASE_URL);
+      this.initialized = true;
+
+      if (process.env.NODE_ENV !== "production") {
+        console.log("✅ Database connection initialized");
+      }
+    } catch (error) {
+      throw new DatabaseError(
+        "Failed to initialize database connection",
+        error instanceof Error ? error.message : "Unknown error",
+      );
+    }
+  }
+
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  // For testing purposes only
+  reset(): void {
+    this.sql = null;
+    this.initialized = false;
+  }
+}
+
+// Export singleton instance methods
+const dbConnection = DatabaseConnection.getInstance();
+
+export const getDbClient = () => dbConnection.getClient();
+export const isConnectionInitialized = () => dbConnection.isInitialized();
+export const resetConnection = () => dbConnection.reset();

netlify/functions/infrastructure/database/index.ts

···
+export * from "./DatabaseConnection";
+export * from "./DatabaseService";

netlify/functions/infrastructure/oauth/index.ts

···
+export * from "./config";
+export * from "./OAuthClientFactory";

netlify/functions/init-db.ts

···
-import { SimpleHandler } from "./shared/types/api.types";
-import { DatabaseService } from "./shared/services/database";
-import { withErrorHandling } from "./shared/middleware";
-import { successResponse } from "./shared/utils";
+import { SimpleHandler } from "./core/types/api.types";
+import { DatabaseService } from "./infrastructure/database/DatabaseService";
+import { withErrorHandling } from "./core/middleware";
+import { successResponse } from "./utils";
 
 const initDbHandler: SimpleHandler = async () => {
   const dbService = new DatabaseService();

netlify/functions/logout.ts

···
-import { SimpleHandler } from "./shared/types/api.types";
-import { SessionService } from "./shared/services/session";
-import { getOAuthConfig } from "./shared/services/oauth";
-import { extractSessionId } from "./shared/middleware";
-import { withErrorHandling } from "./shared/middleware";
+import { ApiError } from "./core/errors";
+import { SimpleHandler } from "./core/types/api.types";
+import { SessionService } from "./services/SessionService";
+import { getOAuthConfig } from "./infrastructure/oauth";
+import { extractSessionId } from "./core/middleware";
+import { withErrorHandling } from "./core/middleware";
 
 const logoutHandler: SimpleHandler = async (event) => {
-  // Only allow POST for logout
   if (event.httpMethod !== "POST") {
-    throw new Error("Method not allowed");
+    throw new ApiError(
+      "Method not allowed",
+      405,
+      `Only POST method is supported for ${event.path}`,
+    );
   }
 
   console.log("[logout] Starting logout process...");
-  console.log("[logout] Cookies received:", event.headers.cookie);
 
   const sessionId = extractSessionId(event);
   console.log("[logout] Session ID from cookie:", sessionId);
 
   if (sessionId) {
-    // Use SessionService to properly clean up both user and OAuth sessions
     await SessionService.deleteSession(sessionId);
     console.log("[logout] Successfully deleted session:", sessionId);
   }
 
-  // Clear the session cookie with matching flags from when it was set
   const config = getOAuthConfig();
   const isDev = config.clientType === "loopback";
 

netlify/functions/oauth-callback.ts

···
-import { SimpleHandler } from "./shared/types/api.types";
-import { createOAuthClient, getOAuthConfig } from "./shared/services/oauth";
-import { userSessions } from "./shared/services/session";
-import { redirectResponse } from "./shared/utils";
-import { withErrorHandling } from "./shared/middleware";
-import { CONFIG } from "./shared/constants";
+import { SimpleHandler } from "./core/types/api.types";
+import { createOAuthClient, getOAuthConfig } from "./infrastructure/oauth";
+import { userSessions } from "./infrastructure/oauth/stores";
+import { redirectResponse } from "./utils";
+import { withErrorHandling } from "./core/middleware";
+import { CONFIG } from "./core/config/constants";
 import * as crypto from "crypto";
 
 const oauthCallbackHandler: SimpleHandler = async (event) => {
···
     return redirectResponse(`${currentUrl}/?error=Missing OAuth parameters`);
   }
 
-  // Create OAuth client using shared helper
   const client = await createOAuthClient();
 
-  // Process the OAuth callback
   const result = await client.callback(params);
 
   console.log(
···
     result.session.did,
   );
 
-  // Store session
   const sessionId = crypto.randomUUID();
   const did = result.session.did;
   await userSessions.set(sessionId, { did });
 
   console.log("[oauth-callback] Created user session:", sessionId);
 
-  // Cookie flags - no Secure flag for loopback
   const cookieFlags = isDev
     ? `HttpOnly; SameSite=Lax; Max-Age=${CONFIG.COOKIE_MAX_AGE}; Path=/`
     : `HttpOnly; SameSite=Lax; Max-Age=${CONFIG.COOKIE_MAX_AGE}; Path=/; Secure`;

netlify/functions/oauth-start.ts

···
-import { SimpleHandler } from "./shared/types/api.types";
-import { createOAuthClient } from "./shared/services/oauth";
-import { successResponse } from "./shared/utils";
-import { withErrorHandling } from "./shared/middleware";
-import { ValidationError } from "./shared/constants/errors";
+import { SimpleHandler } from "./core/types/api.types";
+import { createOAuthClient } from "./infrastructure/oauth/OAuthClientFactory";
+import { successResponse } from "./utils";
+import { withErrorHandling } from "./core/middleware";
+import { ValidationError } from "./core/errors";
 
 interface OAuthStartRequestBody {
   login_hint?: string;
···
 
   console.log("[oauth-start] Starting OAuth flow for:", loginHint);
 
-  // Create OAuth client using shared helper
   const client = await createOAuthClient(event);
 
-  // Start the authorization flow
   const authUrl = await client.authorize(loginHint, {
     scope: "atproto transition:generic",
   });

netlify/functions/repositories/BaseRepository.ts

···
+import { getDbClient } from "../infrastructure/database/DatabaseConnection";
+import { NeonQueryFunction } from "@neondatabase/serverless";
+
+export abstract class BaseRepository {
+  protected sql: NeonQueryFunction<any, any>;
+
+  constructor() {
+    this.sql = getDbClient();
+  }
+
+  /**
+   * Execute a raw query
+   */
+  protected async query<T>(
+    queryFn: (sql: NeonQueryFunction<any, any>) => Promise<T>,
+  ): Promise<T> {
+    return await queryFn(this.sql);
+  }
+
+  /**
+   * Helper: Build UNNEST arrays for bulk operations
+   * Returns arrays organized by column for UNNEST pattern
+   */
+  protected buildUnnestArrays<T extends any[]>(
+    columns: string[],
+    rows: T[],
+  ): any[][] {
+    return columns.map((_, colIndex) => rows.map((row) => row[colIndex]));
+  }
+
+  /**
+   * Helper: Extract results into a Map
+   * Common pattern for bulk operations that return id mappings
+   */
+  protected buildIdMap<T extends Record<string, any>>(
+    results: T[],
+    keyField: string,
+    valueField: string = "id",
+  ): Map<string, number> {
+    const map = new Map<string, number>();
+    for (const row of results) {
+      map.set(row[keyField], row[valueField]);
+    }
+    return map;
+  }
+}

netlify/functions/save-results.ts

···
-import { AuthenticatedHandler } from "./shared/types";
+import { AuthenticatedHandler } from "./core/types";
 import {
   UploadRepository,
   SourceAccountRepository,
   MatchRepository,
-} from "./shared/repositories";
-import { successResponse } from "./shared/utils";
-import { normalize } from "./shared/utils";
-import { withAuthErrorHandling } from "./shared/middleware";
-import { ValidationError } from "./shared/constants/errors";
+} from "./repositories";
+import { successResponse } from "./utils";
+import { normalize } from "./utils/string.utils";
+import { withAuthErrorHandling } from "./core/middleware";
+import { ValidationError } from "./core/errors";
 
 interface SearchResult {
   sourceUser: {
···
 }
 
 const saveResultsHandler: AuthenticatedHandler = async (context) => {
-  // Parse request body
   const body: SaveResultsRequest = JSON.parse(context.event.body || "{}");
   const { uploadId, sourcePlatform, results, saveData } = body;
 
···
     );
   }
 
-  // Server-side validation for saveData flag, controlled by frontend
   if (saveData === false) {
     console.log(
       `User ${context.did} has data storage disabled - skipping save`,
···
   const matchRepo = new MatchRepository();
   let matchedCount = 0;
 
-  // Check for recent uploads from this user
   const hasRecent = await uploadRepo.hasRecentUpload(context.did);
   if (hasRecent) {
     console.log(
···
     });
   }
 
-  // Create upload record FIRST
   await uploadRepo.createUpload(
     uploadId,
     context.did,
···
     0,
   );
 
-  // BULK OPERATION 1: Create all source accounts at once
   const allUsernames = results.map((r) => r.sourceUser.username);
   const sourceAccountIdMap = await sourceAccountRepo.bulkCreate(
     sourcePlatform,
     allUsernames,
   );
 
-  // BULK OPERATION 2: Link all users to source accounts
   const links = results
     .map((result) => {
       const normalized = normalize(result.sourceUser.username);
···
 
   await sourceAccountRepo.linkUserToAccounts(uploadId, context.did, links);
 
-  // BULK OPERATION 3: Store all atproto matches at once
   const allMatches: Array<{
     sourceAccountId: number;
     atprotoDid: string;
···
     }
   }
 
-  // Store all matches in one operation
   let matchIdMap = new Map<string, number>();
   if (allMatches.length > 0) {
     matchIdMap = await matchRepo.bulkStoreMatches(allMatches);
   }
 
-  // BULK OPERATION 4: Mark all matched source accounts
   if (matchedSourceAccountIds.length > 0) {
     await sourceAccountRepo.markAsMatched(matchedSourceAccountIds);
   }
 
-  // BULK OPERATION 5: Create all user match statuses
   const statuses: Array<{
     did: string;
     atprotoMatchId: number;
···
     await matchRepo.upsertUserMatchStatus(statuses);
   }
 
-  // Update upload record with final counts
   await uploadRepo.updateMatchCounts(
     uploadId,
     matchedCount,

netlify/functions/services/FollowService.ts

···
+import { Agent } from "@atproto/api";
+
+interface FollowStatusResult {
+  [did: string]: boolean;
+}
+
+/**
+ * Centralized Follow Service
+ * Handles all follow-related operations to eliminate duplication
+ **/
+export class FollowService {
+  /**
+   * Check follow status for multiple DIDs
+   * Returns a map of DID -> isFollowing
+   **/
+  static async checkFollowStatus(
+    agent: Agent,
+    userDid: string,
+    dids: string[],
+    followLexicon: string = "app.bsky.graph.follow",
+  ): Promise<FollowStatusResult> {
+    const followStatus: FollowStatusResult = {};
+
+    // Initialize all as not following
+    dids.forEach((did) => {
+      followStatus[did] = false;
+    });
+
+    if (dids.length === 0) {
+      return followStatus;
+    }
+
+    try {
+      let cursor: string | undefined = undefined;
+      let hasMore = true;
+      const didsSet = new Set(dids);
+
+      while (hasMore && didsSet.size > 0) {
+        const response = await agent.api.com.atproto.repo.listRecords({
+          repo: userDid,
+          collection: followLexicon,
+          limit: 100,
+          cursor,
+        });
+
+        // Check each record
+        for (const record of response.data.records) {
+          const followRecord = record.value as any;
+          if (followRecord?.subject && didsSet.has(followRecord.subject)) {
+            followStatus[followRecord.subject] = true;
+            didsSet.delete(followRecord.subject); // Found it, no need to keep checking
+          }
+        }
+
+        cursor = response.data.cursor;
+        hasMore = !!cursor;
+
+        // If we've found all DIDs, break early
+        if (didsSet.size === 0) {
+          break;
+        }
+      }
+    } catch (error) {
+      console.error("Error checking follow status:", error);
+      // Return all as false on error (fail-safe)
+    }
+
+    return followStatus;
+  }
+
+  /**
+   * Get list of already followed DIDs from a set
+   **/
+  static async getAlreadyFollowing(
+    agent: Agent,
+    userDid: string,
+    dids: string[],
+    followLexicon: string = "app.bsky.graph.follow",
+  ): Promise<Set<string>> {
+    const followStatus = await this.checkFollowStatus(
+      agent,
+      userDid,
+      dids,
+      followLexicon,
+    );
+
+    return new Set(
+      Object.entries(followStatus)
+        .filter(([_, isFollowing]) => isFollowing)
+        .map(([did]) => did),
+    );
+  }
+}

netlify/functions/services/SessionService.ts

···
+import { Agent } from "@atproto/api";
+import type { NodeOAuthClient } from "@atproto/oauth-client-node";
+import type { HandlerEvent } from "@netlify/functions";
+import { AuthenticationError, ERROR_MESSAGES } from "../core/errors";
+import { createOAuthClient } from "../infrastructure/oauth";
+import { userSessions } from "../infrastructure/oauth/stores";
+import { configCache } from "../infrastructure/cache/CacheService";
+
+export class SessionService {
+  static async getAgentForSession(
+    sessionId: string,
+    event?: HandlerEvent,
+  ): Promise<{
+    agent: Agent;
+    did: string;
+    client: NodeOAuthClient;
+  }> {
+    console.log("[SessionService] Getting agent for session:", sessionId);
+
+    const userSession = await userSessions.get(sessionId);
+    if (!userSession) {
+      throw new AuthenticationError(ERROR_MESSAGES.INVALID_SESSION);
+    }
+
+    const did = userSession.did;
+    console.log("[SessionService] Found user session for DID:", did);
+
+    // Cache the OAuth client per session for 5 minutes
+    const cacheKey = `oauth-client-${sessionId}`;
+    let client = configCache.get(cacheKey) as NodeOAuthClient | null;
+
+    if (!client) {
+      client = await createOAuthClient(event);
+      configCache.set(cacheKey, client, 5 * 60 * 1000); // 5 minutes
+      console.log("[SessionService] Created and cached OAuth client");
+    } else {
+      console.log("[SessionService] Using cached OAuth client");
+    }
+
+    const oauthSession = await client.restore(did);
+    console.log("[SessionService] Restored OAuth session for DID:", did);
+
+    const agent = new Agent(oauthSession);
+
+    return { agent, did, client };
+  }
+
+  static async deleteSession(sessionId: string): Promise<void> {
+    console.log("[SessionService] Deleting session:", sessionId);
+
+    const userSession = await userSessions.get(sessionId);
+    if (!userSession) {
+      console.log("[SessionService] Session not found:", sessionId);
+      return;
+    }
+
+    const did = userSession.did;
+
+    try {
+      const client = await createOAuthClient();
+      await client.revoke(did);
+      console.log("[SessionService] Revoked OAuth session for DID:", did);
+    } catch (error) {
+      console.log("[SessionService] Could not revoke OAuth session:", error);
+    }
+
+    await userSessions.del(sessionId);
+
+    // Clear cached OAuth client
+    configCache.delete(`oauth-client-${sessionId}`);
+
+    console.log("[SessionService] Deleted user session:", sessionId);
+  }
+
+  static async verifySession(sessionId: string): Promise<boolean> {
+    const userSession = await userSessions.get(sessionId);
+    return userSession !== undefined;
+  }
+
+  static async getDIDForSession(sessionId: string): Promise<string | null> {
+    const userSession = await userSessions.get(sessionId);
+    return userSession?.did || null;
+  }
+}

netlify/functions/session.ts

···
-import { SimpleHandler } from "./shared/types/api.types";
-import { SessionService } from "./shared/services/session";
-import { extractSessionId } from "./shared/middleware";
-import { successResponse } from "./shared/utils";
-import { withErrorHandling } from "./shared/middleware";
-import { AuthenticationError, ERROR_MESSAGES } from "./shared/constants/errors";
-
-// In-memory cache for profile
-const profileCache = new Map<string, { data: any; timestamp: number }>();
-const PROFILE_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+import { SimpleHandler } from "./core/types/api.types";
+import { SessionService } from "./services/SessionService";
+import { extractSessionId } from "./core/middleware";
+import { successResponse } from "./utils";
+import { withErrorHandling } from "./core/middleware";
+import { AuthenticationError, ERROR_MESSAGES } from "./core/errors";
+import { profileCache } from "./infrastructure/cache/CacheService";
 
 const sessionHandler: SimpleHandler = async (event) => {
   const sessionId =
···
     throw new AuthenticationError(ERROR_MESSAGES.NO_SESSION_COOKIE);
   }
 
-  // Verify session exists
   const isValid = await SessionService.verifySession(sessionId);
   if (!isValid) {
     throw new AuthenticationError(ERROR_MESSAGES.INVALID_SESSION);
   }
 
-  // Get DID from session
   const did = await SessionService.getDIDForSession(sessionId);
   if (!did) {
     throw new AuthenticationError(ERROR_MESSAGES.INVALID_SESSION);
   }
 
-  const now = Date.now();
-
-  // Check profile cache
-  const cached = profileCache.get(did);
-  if (cached && now - cached.timestamp < PROFILE_CACHE_TTL) {
+  const cached = profileCache.get<any>(did);
+  if (cached) {
     console.log("Returning cached profile for", did);
-    return successResponse(cached.data, 200, {
+    return successResponse(cached, 200, {
       "Cache-Control": "private, max-age=300",
       "X-Cache-Status": "HIT",
     });
   }
 
-  // Cache miss - fetch full profile
-  const { agent } = await SessionService.getAgentForSession(sessionId);
+  const { agent } = await SessionService.getAgentForSession(sessionId, event);
 
-  // Get profile - throw error if this fails
   const profile = await agent.getProfile({ actor: did });
 
   const profileData = {
···
     description: profile.data.description,
   };
 
-  // Cache the profile data
-  profileCache.set(did, {
-    data: profileData,
-    timestamp: now,
-  });
-
-  // Clean up old profile cache entries
-  if (profileCache.size > 100) {
-    for (const [cachedDid, entry] of profileCache.entries()) {
-      if (now - entry.timestamp > PROFILE_CACHE_TTL) {
-        profileCache.delete(cachedDid);
-      }
-    }
-  }
+  profileCache.set(did, profileData);
 
   return successResponse(profileData, 200, {
     "Cache-Control": "private, max-age=300",

netlify/functions/shared/constants/errors.ts

···
-export class ApiError extends Error {
-  constructor(
-    message: string,
-    public statusCode: number = 500,
-    public details?: string,
-  ) {
-    super(message);
-    this.name = "ApiError";
-  }
-}
-
-export class AuthenticationError extends ApiError {
-  constructor(message: string = "Authentication required", details?: string) {
-    super(message, 401, details);
-    this.name = "AuthenticationError";
-  }
-}
-
-export class ValidationError extends ApiError {
-  constructor(message: string, details?: string) {
-    super(message, 400, details);
-    this.name = "ValidationError";
-  }
-}
-
-export class NotFoundError extends ApiError {
-  constructor(message: string = "Resource not found", details?: string) {
-    super(message, 404, details);
-    this.name = "NotFoundError";
-  }
-}
-
-export class DatabaseError extends ApiError {
-  constructor(message: string = "Database operation failed", details?: string) {
-    super(message, 500, details);
-    this.name = "DatabaseError";
-  }
-}
-
-export const ERROR_MESSAGES = {
-  NO_SESSION_COOKIE: "No session cookie",
-  INVALID_SESSION: "Invalid or expired session",
-  MISSING_PARAMETERS: "Missing required parameters",
-  OAUTH_FAILED: "OAuth authentication failed",
-  DATABASE_ERROR: "Database operation failed",
-  PROFILE_FETCH_FAILED: "Failed to fetch profile",
-  SEARCH_FAILED: "Search operation failed",
-  FOLLOW_FAILED: "Follow operation failed",
-  SAVE_FAILED: "Failed to save results",
-} as const;

netlify/functions/shared/constants/index.ts netlify/functions/core/config/constants.ts

···
-export * from "./errors";
-
 export const CONFIG = {
   PROFILE_CACHE_TTL: 5 * 60 * 1000, // 5 minutes
   SESSION_EXPIRY: 30 * 24 * 60 * 60 * 1000, // 30 days

netlify/functions/shared/index.ts

···
-export * from "./types";
-export * from "./constants";
-export * from "./utils";
-export * from "./middleware";
-export * from "./services/database";
-export * from "./services/session";
-export * from "./services/oauth";

netlify/functions/shared/middleware/auth.middleware.ts netlify/functions/core/middleware/auth.middleware.ts

···
 import { HandlerEvent } from "@netlify/functions";
 import cookie from "cookie";
-import { userSessions } from "../services/session/stores";
-import { AuthenticationError, ERROR_MESSAGES } from "../constants/errors";
+import { userSessions } from "../../infrastructure/oauth/stores";
+import { AuthenticationError, ERROR_MESSAGES } from "../errors";
 import { AuthenticatedContext } from "../types";
 
 /**

netlify/functions/shared/middleware/error.middleware.ts netlify/functions/core/middleware/error.middleware.ts

···
 import { HandlerEvent, HandlerResponse, Handler } from "@netlify/functions";
-import { ApiError } from "../constants/errors";
-import { errorResponse } from "../utils/response.utils";
+import { ApiError } from "../errors";
+import { errorResponse } from "../../utils/";
 import { SimpleHandler, AuthenticatedHandler } from "../types";
 
 /**

netlify/functions/shared/repositories/BaseRepository.ts

···
-import { getDbClient } from "../services/database/connection";
-import { NeonQueryFunction } from "@neondatabase/serverless";
-
-/**
- * Base repository class providing common database access patterns
- **/
-export abstract class BaseRepository {
-  protected sql: NeonQueryFunction<any, any>;
-
-  constructor() {
-    this.sql = getDbClient();
-  }
-
-  /**
-   * Execute a raw query
-   **/
-  protected async query<T>(
-    queryFn: (sql: NeonQueryFunction<any, any>) => Promise<T>,
-  ): Promise<T> {
-    return await queryFn(this.sql);
-  }
-}

netlify/functions/shared/repositories/MatchRepository.ts netlify/functions/repositories/MatchRepository.ts

···
 import { BaseRepository } from "./BaseRepository";
-import { AtprotoMatchRow } from "../types";
 
 export class MatchRepository extends BaseRepository {
-  /**
-   * Store a single atproto match
-   **/
   async storeMatch(
     sourceAccountId: number,
     atprotoDid: string,
···
     return (result as any[])[0].id;
   }
 
-  /**
-   * Bulk store atproto matches
-   **/
   async bulkStoreMatches(
     matches: Array<{
       sourceAccountId: number;
···
   ): Promise<Map<string, number>> {
     if (matches.length === 0) return new Map();
 
-    const sourceAccountId = matches.map((m) => m.sourceAccountId);
-    const atprotoDid = matches.map((m) => m.atprotoDid);
-    const atprotoHandle = matches.map((m) => m.atprotoHandle);
-    const atprotoDisplayName = matches.map((m) => m.atprotoDisplayName || null);
-    const atprotoAvatar = matches.map((m) => m.atprotoAvatar || null);
-    const atprotoDescription = matches.map((m) => m.atprotoDescription || null);
-    const matchScore = matches.map((m) => m.matchScore);
-    const postCount = matches.map((m) => m.postCount || 0);
-    const followerCount = matches.map((m) => m.followerCount || 0);
-    const followStatus = matches.map((m) =>
+    const rows = matches.map((m) => [
+      m.sourceAccountId,
+      m.atprotoDid,
+      m.atprotoHandle,
+      m.atprotoDisplayName || null,
+      m.atprotoAvatar || null,
+      m.atprotoDescription || null,
+      m.matchScore,
+      m.postCount || 0,
+      m.followerCount || 0,
       JSON.stringify(m.followStatus || {}),
+    ]);
+
+    const [
+      sourceAccountIds,
+      atprotoDids,
+      atprotoHandles,
+      atprotoDisplayNames,
+      atprotoAvatars,
+      atprotoDescriptions,
+      matchScores,
+      postCounts,
+      followerCounts,
+      followStatuses,
+    ] = this.buildUnnestArrays(
+      [
+        "source_account_id",
+        "atproto_did",
+        "atproto_handle",
+        "atproto_display_name",
+        "atproto_avatar",
+        "atproto_description",
+        "match_score",
+        "post_count",
+        "follower_count",
+        "follow_status",
+      ],
+      rows,
     );
 
     const result = await this.sql`
···
         match_score, post_count, follower_count, follow_status
       )
       SELECT * FROM UNNEST(
-        ${sourceAccountId}::integer[],
-        ${atprotoDid}::text[],
-        ${atprotoHandle}::text[],
-        ${atprotoDisplayName}::text[],
-        ${atprotoAvatar}::text[],
-        ${atprotoDescription}::text[],
-        ${matchScore}::integer[],
-        ${postCount}::integer[],
-        ${followerCount}::integer[],
-        ${followStatus}::jsonb[]
+        ${sourceAccountIds}::integer[],
+        ${atprotoDids}::text[],
+        ${atprotoHandles}::text[],
+        ${atprotoDisplayNames}::text[],
+        ${atprotoAvatars}::text[],
+        ${atprotoDescriptions}::text[],
+        ${matchScores}::integer[],
+        ${postCounts}::integer[],
+        ${followerCounts}::integer[],
+        ${followStatuses}::jsonb[]
       ) AS t(
         source_account_id, atproto_did, atproto_handle,
         atproto_display_name, atproto_avatar, atproto_description,
···
       RETURNING id, source_account_id, atproto_did
     `;
 
-    // Create map of "sourceAccountId:atprotoDid" to match ID
     const idMap = new Map<string, number>();
     for (const row of result as any[]) {
       idMap.set(`${row.source_account_id}:${row.atproto_did}`, row.id);
···
     return idMap;
   }
 
-  /**
-   * Get upload details with pagination
-   **/
   async getUploadDetails(
     uploadId: string,
     did: string,
···
     results: any[];
     totalUsers: number;
   }> {
-    // First verify upload belongs to user and get total count
     const uploadCheck = await this.sql`
       SELECT upload_id, total_users FROM user_uploads
       WHERE upload_id = ${uploadId} AND did = ${did}
···
     const totalUsers = (uploadCheck as any[])[0].total_users;
     const offset = (page - 1) * pageSize;
 
-    // Fetch paginated results
     const results = await this.sql`
       SELECT
         sa.source_username,
···
     };
   }
 
-  /**
-   * Update follow status for a match
-   **/
   async updateFollowStatus(
     atprotoDid: string,
     followLexicon: string,
···
     `;
   }
 
-  /**
-   * Create or update user match status
-   **/
   async upsertUserMatchStatus(
     statuses: Array<{
       did: string;
···
   ): Promise<void> {
     if (statuses.length === 0) return;
 
-    const did = statuses.map((s) => s.did);
-    const atprotoMatchId = statuses.map((s) => s.atprotoMatchId);
-    const sourceAccountId = statuses.map((s) => s.sourceAccountId);
-    const viewedFlags = statuses.map((s) => s.viewed);
-    const viewedDates = statuses.map((s) => (s.viewed ? new Date() : null));
+    const rows = statuses.map((s) => [
+      s.did,
+      s.atprotoMatchId,
+      s.sourceAccountId,
+      s.viewed,
+      s.viewed ? new Date().toISOString() : null,
+    ]);
+
+    const [dids, atprotoMatchIds, sourceAccountIds, viewedFlags, viewedDates] =
+      this.buildUnnestArrays(
+        ["did", "atproto_match_id", "source_account_id", "viewed", "viewed_at"],
+        rows,
+      );
 
     await this.sql`
       INSERT INTO user_match_status (did, atproto_match_id, source_account_id, viewed, viewed_at)
       SELECT * FROM UNNEST(
-        ${did}::text[],
-        ${atprotoMatchId}::integer[],
-        ${sourceAccountId}::integer[],
+        ${dids}::text[],
+        ${atprotoMatchIds}::integer[],
+        ${sourceAccountIds}::integer[],
         ${viewedFlags}::boolean[],
         ${viewedDates}::timestamp[]
       ) AS t(did, atproto_match_id, source_account_id, viewed, viewed_at)

netlify/functions/shared/repositories/SourceAccountRepository.ts netlify/functions/repositories/SourceAccountRepository.ts

···
 import { BaseRepository } from "./BaseRepository";
-import { normalize } from "../utils";
+import { normalize } from "../utils/string.utils";
 
 export class SourceAccountRepository extends BaseRepository {
-  /**
-   * Get or create a source account
-   **/
   async getOrCreate(
     sourcePlatform: string,
     sourceUsername: string,
···
     return (result as any[])[0].id;
   }
 
-  /**
-   * Bulk create source accounts
-   **/
   async bulkCreate(
     sourcePlatform: string,
     usernames: string[],
   ): Promise<Map<string, number>> {
-    const values = usernames.map((username) => ({
-      platform: sourcePlatform,
-      username: username,
-      normalized: normalize(username),
-    }));
+    // Prepare data
+    const rows = usernames.map((username) => [
+      sourcePlatform,
+      username,
+      normalize(username),
+    ]);
 
-    const platforms = values.map((v) => v.platform);
-    const source_usernames = values.map((v) => v.username);
-    const normalized = values.map((v) => v.normalized);
+    // Use helper to build UNNEST arrays
+    const [platforms, sourceUsernames, normalized] = this.buildUnnestArrays(
+      ["source_platform", "source_username", "normalized_username"],
+      rows,
+    );
 
+    // Execute with Neon's template syntax
     const result = await this.sql`
       INSERT INTO source_accounts (source_platform, source_username, normalized_username)
-      SELECT *
-      FROM UNNEST(
+      SELECT * FROM UNNEST(
         ${platforms}::text[],
-        ${source_usernames}::text[],
+        ${sourceUsernames}::text[],
         ${normalized}::text[]
       ) AS t(source_platform, source_username, normalized_username)
       ON CONFLICT (source_platform, normalized_username) DO UPDATE
···
       RETURNING id, normalized_username
     `;
 
-    // Create map of normalized username to ID
-    const idMap = new Map<string, number>();
-    for (const row of result as any[]) {
-      idMap.set(row.normalized_username, row.id);
-    }
-
-    return idMap;
+    // Use helper to build result map
+    return this.buildIdMap(result as any[], "normalized_username", "id");
   }
 
-  /**
-   * Mark source accounts as matched
-   **/
   async markAsMatched(sourceAccountIds: number[]): Promise<void> {
     if (sourceAccountIds.length === 0) return;
 
···
     `;
   }
 
-  /**
-   * Link user to source accounts
-   **/
   async linkUserToAccounts(
     uploadId: string,
     did: string,
     links: Array<{ sourceAccountId: number; sourceDate: string }>,
   ): Promise<void> {
-    const numLinks = links.length;
-    if (numLinks === 0) return;
+    if (links.length === 0) return;
+
+    const rows = links.map((l) => [
+      uploadId,
+      did,
+      l.sourceAccountId,
+      l.sourceDate,
+    ]);
 
-    const sourceAccountIds = links.map((l) => l.sourceAccountId);
-    const sourceDates = links.map((l) => l.sourceDate);
-    const uploadIds = Array(numLinks).fill(uploadId);
-    const dids = Array(numLinks).fill(did);
+    const [uploadIds, dids, sourceAccountIds, sourceDates] =
+      this.buildUnnestArrays(
+        ["upload_id", "did", "source_account_id", "source_date"],
+        rows,
+      );
 
     await this.sql`
       INSERT INTO user_source_follows (upload_id, did, source_account_id, source_date)

netlify/functions/shared/repositories/UploadRepository.ts netlify/functions/repositories/UploadRepository.ts

···
 import { BaseRepository } from "./BaseRepository";
-import { UserUploadRow } from "../types";
+import { UserUploadRow } from "../core/types";
 
 export class UploadRepository extends BaseRepository {
   /**

netlify/functions/shared/repositories/index.ts netlify/functions/repositories/index.ts

···
-export * from "./BaseRepository";
 export * from "./UploadRepository";
 export * from "./SourceAccountRepository";
 export * from "./MatchRepository";

netlify/functions/shared/services/database/DatabaseService.ts netlify/functions/infrastructure/database/DatabaseService.ts

···
-import { getDbClient } from "./connection";
-import { DatabaseError } from "../../constants/errors";
+import { getDbClient } from "./DatabaseConnection";
+import { DatabaseError } from "../../core/errors";
+import { DbStatusRow } from "../../core/types";
 
 export class DatabaseService {
   private sql = getDbClient();
···
         process.env.NETLIFY_DATABASE_URL?.split("@")[1],
       );
 
-      // Test connection
       const res = (await this
-        .sql`SELECT current_database() AS db, current_user AS user, NOW() AS now`) as Record<
-        string,
-        any
-      >[];
+        .sql`SELECT current_database() AS db, current_user AS user, NOW() AS now`) as DbStatusRow[];
       console.log("✅ Connected:", res[0]);
 
-      // Create tables
       await this.createTables();
       await this.createIndexes();
 
···
   }
 
   private async createTables(): Promise<void> {
-    // OAuth Tables
     await this.sql`
       CREATE TABLE IF NOT EXISTS oauth_states (
         key TEXT PRIMARY KEY,
···
       )
     `;
 
-    // User + Match Tracking
     await this.sql`
       CREATE TABLE IF NOT EXISTS user_uploads (
         upload_id TEXT PRIMARY KEY,
···
   }
 
   private async createIndexes(): Promise<void> {
-    // Existing indexes
     await this
       .sql`CREATE INDEX IF NOT EXISTS idx_source_accounts_to_check ON source_accounts(source_platform, match_found, last_checked)`;
     await this
···
       .sql`CREATE INDEX IF NOT EXISTS idx_user_match_status_did_followed ON user_match_status(did, followed)`;
     await this
       .sql`CREATE INDEX IF NOT EXISTS idx_notification_queue_pending ON notification_queue(sent, created_at) WHERE sent = false`;
-
-    // Enhanced indexes
     await this
       .sql`CREATE INDEX IF NOT EXISTS idx_atproto_matches_stats ON atproto_matches(source_account_id, found_at DESC, post_count DESC, follower_count DESC)`;
     await this

netlify/functions/shared/services/database/connection.ts

···
-import { neon, NeonQueryFunction } from "@neondatabase/serverless";
-import { DatabaseError } from "../../constants/errors";
-
-let sqlInstance: NeonQueryFunction<any, any> | undefined = undefined;
-let connectionInitialized = false;
-
-export function getDbClient(): NeonQueryFunction<any, any> {
-  if (!sqlInstance) {
-    if (!process.env.NETLIFY_DATABASE_URL) {
-      throw new DatabaseError(
-        "Database connection string not configured",
-        "NETLIFY_DATABASE_URL environment variable is missing",
-      );
-    }
-
-    try {
-      sqlInstance = neon(process.env.NETLIFY_DATABASE_URL);
-      connectionInitialized = true;
-      if (process.env.NODE_ENV !== "production") {
-        console.log("✅ Database connection initialized");
-      }
-    } catch (error) {
-      throw new DatabaseError(
-        "Failed to initialize database connection",
-        error instanceof Error ? error.message : "Unknown error",
-      );
-    }
-  }
-
-  return sqlInstance;
-}
-
-export function isConnectionInitialized(): boolean {
-  return connectionInitialized;
-}
-
-// Reset connection (useful for testing)
-export function resetConnection(): void {
-  sqlInstance = undefined;
-  connectionInitialized = false;
-}

netlify/functions/shared/services/database/index.ts

···
-export * from "./connection";
-export * from "./DatabaseService";

netlify/functions/shared/services/oauth/client.factory.ts netlify/functions/infrastructure/oauth/OAuthClientFactory.ts

···
   atprotoLoopbackClientMetadata,
 } from "@atproto/oauth-client-node";
 import { JoseKey } from "@atproto/jwk-jose";
-import { stateStore, sessionStore } from "../session/stores";
+import { ApiError } from "../../core/errors";
+import { stateStore, sessionStore } from "./stores";
 import { getOAuthConfig } from "./config";
 
 function normalizePrivateKey(key: string): string {
···
   return key;
 }
 
-/**
- * Creates and returns a configured OAuth client based on environment
- * Centralizes the client creation logic used across all endpoints
- **/
 export async function createOAuthClient(event?: {
   headers: Record<string, string | undefined>;
 }): Promise<NodeOAuthClient> {
···
   const isDev = config.clientType === "loopback";
 
   if (isDev) {
-    // Loopback mode for local development
     console.log("[oauth-client] Creating loopback OAuth client");
     const clientMetadata = atprotoLoopbackClientMetadata(config.clientId);
 
···
       sessionStore: sessionStore as any,
     });
   } else {
-    // Production mode with private key
     console.log("[oauth-client] Creating production OAuth client");
 
     if (!process.env.OAUTH_PRIVATE_KEY) {
-      throw new Error("OAUTH_PRIVATE_KEY is required for production");
+      throw new ApiError(
+        "OAuth client key missing",
+        500,
+        "OAUTH_PRIVATE_KEY environment variable is required for production client setup.",
+      );
     }
 
     const normalizedKey = normalizePrivateKey(process.env.OAUTH_PRIVATE_KEY);

netlify/functions/shared/services/oauth/config.ts netlify/functions/infrastructure/oauth/config.ts

···
-import { OAuthConfig } from "../../types";
-import { configCache } from "../../utils/cache.utils";
+import { OAuthConfig } from "../../core/types";
+import { ApiError } from "../../core/errors";
+import { configCache } from "../cache/CacheService";
 
 export function getOAuthConfig(event?: {
   headers: Record<string, string | undefined>;
 }): OAuthConfig {
-  // Create a cache key based on the environment
   const host = event?.headers?.host || "default";
   const cacheKey = `oauth-config-${host}`;
 
-  // Check cache first
   const cached = configCache.get(cacheKey) as OAuthConfig | undefined;
   if (cached) {
     return cached;
···
   let deployContext: string | undefined;
 
   if (event?.headers) {
-    // Get deploy context from Netlify headers
     deployContext = event.headers["x-nf-deploy-context"];
-
-    // For Netlify deploys, construct URL from host header
     const forwardedProto = event.headers["x-forwarded-proto"] || "https";
 
     if (host && !host.includes("localhost") && !host.includes("127.0.0.1")) {
···
     }
   }
 
-  // Fallback to environment variables (prioritize DEPLOY_URL over URL for preview deploys)
   if (!baseUrl) {
     baseUrl = process.env.DEPLOY_URL || process.env.URL;
   }
···
     },
   });
 
-  // Development: loopback client for local dev
   const isLocalhost =
     !baseUrl || baseUrl.includes("localhost") || baseUrl.includes("127.0.0.1");
 
···
       clientType: "loopback",
     };
   } else {
-    // Production/Preview: discoverable client
     if (!baseUrl) {
-      throw new Error("No public URL available for OAuth configuration");
+      throw new ApiError(
+        "No public URL available for OAuth configuration",
+        500,
+        "Missing DEPLOY_URL or URL environment variables.",
+      );
     }
 
     console.log("Using confidential OAuth client for:", baseUrl);
···
     };
   }
 
-  // Cache the config for 5 minutes (300000ms)
   configCache.set(cacheKey, config, 300000);
 
   return config;

netlify/functions/shared/services/oauth/index.ts

···
-export * from "./config";
-export * from "./client.factory";

netlify/functions/shared/services/session/SessionService.ts

···
-import { Agent } from "@atproto/api";
-import { createOAuthClient } from "../oauth/client.factory";
-import { userSessions } from "./stores";
-import type { NodeOAuthClient } from "@atproto/oauth-client-node";
-import { AuthenticationError, ERROR_MESSAGES } from "../../constants/errors";
-
-/**
- * Session Manager - Coordinates between user sessions and OAuth sessions
- * Provides a clean interface for session operations across the application
- **/
-export class SessionService {
-  /**
-   * Get an authenticated Agent for a given session ID
-   * Handles both user session lookup and OAuth session restoration
-   **/
-  static async getAgentForSession(sessionId: string): Promise<{
-    agent: Agent;
-    did: string;
-    client: NodeOAuthClient;
-  }> {
-    console.log("[SessionService] Getting agent for session:", sessionId);
-
-    // Get user session
-    const userSession = await userSessions.get(sessionId);
-    if (!userSession) {
-      throw new AuthenticationError(ERROR_MESSAGES.INVALID_SESSION);
-    }
-
-    const did = userSession.did;
-    console.log("[SessionService] Found user session for DID:", did);
-
-    // Create OAuth client
-    const client = await createOAuthClient();
-
-    // Restore OAuth session
-    const oauthSession = await client.restore(did);
-    console.log("[SessionService] Restored OAuth session for DID:", did);
-
-    // Create agent from OAuth session
-    const agent = new Agent(oauthSession);
-
-    return { agent, did, client };
-  }
-
-  /**
-   * Delete a session and clean up associated OAuth sessions
-   * Ensures both user_sessions and oauth_sessions are cleaned up
-   **/
-  static async deleteSession(sessionId: string): Promise<void> {
-    console.log("[SessionService] Deleting session:", sessionId);
-
-    // Get user session first
-    const userSession = await userSessions.get(sessionId);
-    if (!userSession) {
-      console.log("[SessionService] Session not found:", sessionId);
-      return;
-    }
-
-    const did = userSession.did;
-
-    try {
-      // Create OAuth client and revoke the session
-      const client = await createOAuthClient();
-
-      // Try to revoke at the PDS (this also deletes from oauth_sessions)
-      await client.revoke(did);
-      console.log("[SessionService] Revoked OAuth session for DID:", did);
-    } catch (error) {
-      // If revocation fails, the OAuth session might already be invalid
-      console.log("[SessionService] Could not revoke OAuth session:", error);
-    }
-
-    // Delete user session
-    await userSessions.del(sessionId);
-    console.log("[SessionService] Deleted user session:", sessionId);
-  }
-
-  /**
-   * Verify a session exists and is valid
-   **/
-  static async verifySession(sessionId: string): Promise<boolean> {
-    const userSession = await userSessions.get(sessionId);
-    return userSession !== undefined;
-  }
-
-  /**
-   * Get the DID for a session without creating an agent
-   **/
-  static async getDIDForSession(sessionId: string): Promise<string | null> {
-    const userSession = await userSessions.get(sessionId);
-    return userSession?.did || null;
-  }
-}

netlify/functions/shared/services/session/index.ts

···
-export * from "./SessionService";
-export * from "./stores";

netlify/functions/shared/services/session/stores/SessionStore.ts netlify/functions/infrastructure/oauth/stores/SessionStore.ts

···
-import { getDbClient } from "../../database/connection";
-import { SessionData, OAuthSessionRow } from "../../../types";
-import { CONFIG } from "../../../constants";
+import { getDbClient } from "../../database";
+import { SessionData, OAuthSessionRow } from "../../../core/types";
+import { CONFIG } from "../../../core/config/constants";
 
 export class PostgresSessionStore {
   private sql = getDbClient();

netlify/functions/shared/services/session/stores/StateStore.ts netlify/functions/infrastructure/oauth/stores/StateStore.ts

···
-import { getDbClient } from "../../database/connection";
-import { StateData, OAuthStateRow } from "../../../types";
-import { CONFIG } from "../../../constants";
+import { getDbClient } from "../../database";
+import { StateData, OAuthStateRow } from "../../../core/types";
+import { CONFIG } from "../../../core/config/constants";
 
 export class PostgresStateStore {
   private sql = getDbClient();

netlify/functions/shared/services/session/stores/UserSessionStore.ts netlify/functions/infrastructure/oauth/stores/UserSessionStore.ts

···
-import { getDbClient } from "../../database/connection";
-import { UserSessionData, UserSessionRow } from "../../../types";
-import { CONFIG } from "../../../constants";
+import { getDbClient } from "../../database";
+import { UserSessionData, UserSessionRow } from "../../../core/types";
+import { CONFIG } from "../../../core/config/constants";
 
 export class PostgresUserSessionStore {
   private sql = getDbClient();

netlify/functions/shared/types/database.types.ts netlify/functions/core/types/database.types.ts

···
   dismissed_at: Date | null;
 }
 
+export interface DbStatusRow {
+  db: string;
+  user: string;
+  now: Date;
+}
+
 export interface NotificationQueueRow {
   id: number;
   did: string;

netlify/functions/shared/utils/cache.utils.ts

···
-/**
- * Simple in-memory cache with TTL support
- **/
-class SimpleCache<T> {
-  private cache = new Map<string, { value: T; expires: number }>();
-
-  set(key: string, value: T, ttlMs: number): void {
-    this.cache.set(key, {
-      value,
-      expires: Date.now() + ttlMs,
-    });
-  }
-
-  get(key: string): T | undefined {
-    const entry = this.cache.get(key);
-    if (!entry) return undefined;
-
-    if (Date.now() > entry.expires) {
-      this.cache.delete(key);
-      return undefined;
-    }
-
-    return entry.value;
-  }
-
-  has(key: string): boolean {
-    return this.get(key) !== undefined;
-  }
-
-  delete(key: string): void {
-    this.cache.delete(key);
-  }
-
-  clear(): void {
-    this.cache.clear();
-  }
-
-  // Clean up expired entries
-  cleanup(): void {
-    const now = Date.now();
-    for (const [key, entry] of this.cache.entries()) {
-      if (now > entry.expires) {
-        this.cache.delete(key);
-      }
-    }
-  }
-}
-
-export const configCache = new SimpleCache<any>();

netlify/functions/shared/utils/index.ts netlify/functions/utils/index.ts

···
 export * from "./response.utils";
-export * from "./cache.utils";
 export * from "./string.utils";

netlify/functions/shared/utils/response.utils.ts netlify/functions/utils/response.utils.ts

···
 import { HandlerResponse } from "@netlify/functions";
-import { ApiResponse } from "../types";
+import { ApiResponse } from "../core/types";
 
 export function successResponse<T>(
   data: T,

src/App.tsx

···
 import HomePage from "./pages/Home";
 import LoadingPage from "./pages/Loading";
 import ResultsPage from "./pages/Results";
-import { apiClient } from "./lib/apiClient";
 import { useAuth } from "./hooks/useAuth";
 import { useSearch } from "./hooks/useSearch";
 import { useFollow } from "./hooks/useFollows";
 import { useFileUpload } from "./hooks/useFileUpload";
 import { useTheme } from "./hooks/useTheme";
 import Firefly from "./components/Firefly";
-import { ATPROTO_APPS } from "./constants/atprotoApps";
 import { DEFAULT_SETTINGS } from "./types/settings";
 import type { UserSettings } from "./types/settings";
+import { apiClient } from "./lib/api/client";
+import { ATPROTO_APPS } from "./config/atprotoApps";
 
 export default function App() {
   // Auth hook

src/components/AppHeader.tsx

···
 import { Heart, Home, LogOut, ChevronDown } from "lucide-react";
 import ThemeControls from "./ThemeControls";
 import FireflyLogo from "../assets/at-firefly-logo.svg?react";
+import AvatarWithFallback from "./common/AvatarWithFallback";
 
 interface atprotoSession {
   did: string;
···
                   onClick={() => setShowMenu(!showMenu)}
                   className="flex items-center space-x-3 px-3 py-1 rounded-lg hover:bg-purple-50 dark:hover:bg-slate-800 transition-colors focus:outline-none focus:ring-2 focus:ring-orange-500 dark:focus:ring-amber-400"
                 >
-                  {session?.avatar ? (
-                    <img
-                      src={session.avatar}
-                      alt=""
-                      className="w-8 h-8 rounded-full object-cover"
-                    />
-                  ) : (
-                    <div className="w-8 h-8 bg-gradient-to-br from-cyan-400 to-purple-500 rounded-full flex items-center justify-center shadow-sm">
-                      <span className="text-white font-bold text-sm">
-                        {session?.handle?.charAt(0).toUpperCase()}
-                      </span>
-                    </div>
-                  )}
+                  <AvatarWithFallback
+                    avatar={session?.avatar}
+                    handle={session?.handle || ""}
+                    size="sm"
+                  />
                   <span className="text-sm font-medium text-purple-950 dark:text-cyan-50 hidden sm:inline">
                     @{session?.handle}
                   </span>

src/components/FaviconIcon.tsx

···
-// FaviconIcon.tsx (Conceptual Component Update)
-
 import { useState } from "react";
 import { Globe } from "lucide-react";
 
···
   url: string;
   alt: string;
   className?: string;
-  useButtonStyling?: boolean; // ⬅️ NEW OPTIONAL PROP
+  useButtonStyling?: boolean;
 }
 
 export default function FaviconIcon({

src/components/HistoryTab.tsx

···
 import { Upload, Sparkles, ChevronRight, Database } from "lucide-react";
-import { ATPROTO_APPS } from "../constants/atprotoApps";
+import { ATPROTO_APPS } from "../config/atprotoApps";
 import type { Upload as UploadType } from "../types";
 import FaviconIcon from "../components/FaviconIcon";
 import type { UserSettings } from "../types/settings";
 import { getPlatformColor } from "../lib/utils/platform";
+import { formatRelativeTime } from "../lib/utils/date";
 
 interface HistoryTabProps {
   uploads: UploadType[];
···
 }: HistoryTabProps) {
   const formatDate = (dateString: string) => {
     const date = new Date(dateString);
-    return date.toLocaleDateString("en-US", {
-      month: "short",
-      day: "numeric",
-      year: "numeric",
-      hour: "2-digit",
-      minute: "2-digit",
-    });
+    return formatRelativeTime(date.toLocaleDateString("en-US"));
   };
 
   return (

src/components/PlatformSelector.tsx

···
-import { Twitter, Instagram, Video, Hash, Gamepad2 } from "lucide-react";
-import { PLATFORMS } from "../constants/platforms";
+import { PLATFORMS } from "../config/platforms";
 
 interface PlatformSelectorProps {
   onPlatformSelect: (platform: string) => void;

src/components/SearchResultCard.tsx

···
   UserCheck,
 } from "lucide-react";
 import type { SearchResult } from "../types";
-import { getPlatform, getAtprotoAppWithFallback } from "../lib/utils/platform";
+import { getAtprotoAppWithFallback } from "../lib/utils/platform";
 import type { AtprotoAppId } from "../types/settings";
+import AvatarWithFallback from "./common/AvatarWithFallback";
 
 interface SearchResultCardProps {
   result: SearchResult;
···
                 className="flex items-start gap-3 p-3 cursor-pointer hover:scale-[1.01] transition-transform"
               >
                 {/* Avatar */}
-                {match.avatar ? (
-                  <img
-                    src={match.avatar}
-                    alt="User avatar"
-                    className="w-12 h-12 rounded-full object-cover flex-shrink-0"
-                  />
-                ) : (
-                  <div className="w-12 h-12 rounded-full bg-gradient-to-br from-cyan-400 to-purple-500 flex items-center justify-center flex-shrink-0">
-                    <span className="text-white font-bold">
-                      {match.handle.charAt(0).toUpperCase()}
-                    </span>
-                  </div>
-                )}
+                <AvatarWithFallback
+                  avatar={match.avatar}
+                  handle={match.handle || ""}
+                  size="sm"
+                />
 
                 {/* Match Info */}
                 <div className="flex-1 min-w-0 space-y-1">

src/components/SetupWizard.tsx

···
 import { useState } from "react";
 import { Heart, X, Check, ChevronRight } from "lucide-react";
-import { PLATFORMS } from "../constants/platforms";
-import { ATPROTO_APPS } from "../constants/atprotoApps";
+import { PLATFORMS } from "../config/platforms";
+import { ATPROTO_APPS } from "../config/atprotoApps";
 import type { UserSettings, PlatformDestinations } from "../types/settings";
 
 interface SetupWizardProps {

src/components/common/AvatarWithFallback.tsx

···
+interface AvatarWithFallbackProps {
+  avatar?: string;
+  handle: string;
+  size?: "sm" | "md" | "lg";
+  className?: string;
+}
+
+export default function AvatarWithFallback({
+  avatar,
+  handle,
+  size = "md",
+  className = "",
+}: AvatarWithFallbackProps) {
+  const sizeClasses = {
+    sm: "w-8 h-8 text-sm",
+    md: "w-12 h-12 text-base",
+    lg: "w-16 h-16 text-xl",
+  };
+
+  const sizeClass = sizeClasses[size];
+
+  if (avatar) {
+    return (
+      <img
+        src={avatar}
+        alt={`${handle}'s avatar`}
+        className={`${sizeClass} rounded-full object-cover ${className}`}
+      />
+    );
+  }
+
+  return (
+    <div
+      className={`${sizeClass} bg-gradient-to-br from-cyan-400 to-purple-500 rounded-full flex items-center justify-center shadow-sm ${className}`}
+    >
+      <span className="text-white font-bold">
+        {handle.charAt(0).toUpperCase()}
+      </span>
+    </div>
+  );
+}

src/config/constants.ts

···
+export const SEARCH_CONFIG = {
+  BATCH_SIZE: 25,
+  MAX_MATCHES: 1000,
+} as const;
+
+export const FOLLOW_CONFIG = {
+  BATCH_SIZE: 50,
+} as const;
+
+export const CACHE_CONFIG = {
+  DEFAULT_TTL: 5 * 60 * 1000, // 5 minutes
+  PROFILE_TTL: 5 * 60 * 1000,
+  UPLOAD_LIST_TTL: 2 * 60 * 1000,
+  UPLOAD_DETAILS_TTL: 10 * 60 * 1000,
+  SEARCH_RESULTS_TTL: 10 * 60 * 1000,
+  FOLLOW_STATUS_TTL: 2 * 60 * 1000,
+} as const;

src/config/env.ts

···
+/**
+ * Environment configuration
+ * Centralizes all environment variable access and validation
+ */
+
+// Determine environment
+const nodeEnv = import.meta.env.MODE || "development";
+
+export const ENV = {
+  // Environment
+  NODE_ENV: nodeEnv,
+  IS_DEVELOPMENT: nodeEnv === "development",
+  IS_PRODUCTION: nodeEnv === "production",
+  IS_TEST: nodeEnv === "test",
+
+  // Feature flags
+  IS_LOCAL_MOCK: import.meta.env.VITE_LOCAL_MOCK === "true",
+  ENABLE_OAUTH: import.meta.env.VITE_ENABLE_OAUTH !== "false",
+  ENABLE_DATABASE: import.meta.env.VITE_ENABLE_DATABASE !== "false",
+
+  // API
+  API_BASE: import.meta.env.VITE_API_BASE || "/.netlify/functions",
+} as const;
+
+export function isLocalMockMode(): boolean {
+  return ENV.IS_LOCAL_MOCK;
+}
+
+export function getApiUrl(endpoint: string): string {
+  return `${ENV.API_BASE}/${endpoint}`;
+}

src/constants/platforms.ts src/config/platforms.ts

···
     defaultApp: "bluesky",
   },
 };
-
-export const SEARCH_CONFIG = {
-  BATCH_SIZE: 25,
-  MAX_MATCHES: 1000,
-};
-
-export const FOLLOW_CONFIG = {
-  BATCH_SIZE: 50,
-};
-
-/**
- * @deprecated Use getPlatformColor from lib/utils/platform instead
- **/
-export function getLegacyPlatformColor(platform: string): string {
-  const colors: Record<string, string> = {
-    tiktok: "from-black via-gray-800 to-cyan-400",
-    twitter: "from-blue-400 to-blue-600",
-    instagram: "from-pink-500 via-purple-500 to-orange-500",
-  };
-  return colors[platform] || "from-gray-400 to-gray-600";
-}

src/hooks/useAuth.ts

···
 import { useState, useEffect } from "react";
-import { apiClient } from "../lib/apiClient";
+import { apiClient } from "../lib/api/client";
 import type { AtprotoSession, AppStep } from "../types";
 
 export function useAuth() {
···
         return;
       }
 
-      // If we have a session parameter in URL, this is an OAuth callback
       if (sessionId) {
         console.log("[useAuth] Session ID in URL:", sessionId);
         setStatusMessage("Loading your session...");
 
-        // Single call now gets both session AND profile data
         const data = await apiClient.getSession();
-        setSession({
-          did: data.did,
-          handle: data.handle,
-          displayName: data.displayName,
-          avatar: data.avatar,
-          description: data.description,
-        });
+        setSession(data);
         setCurrentStep("home");
         setStatusMessage(`Welcome back, ${data.handle}!`);
 
···
         return;
       }
 
-      // Otherwise, check if there's an existing session cookie
-      // Single call now gets both session AND profile data
       console.log("[useAuth] Checking for existing session cookie...");
       const data = await apiClient.getSession();
       console.log("[useAuth] Found existing session:", data);
-      setSession({
-        did: data.did,
-        handle: data.handle,
-        displayName: data.displayName,
-        avatar: data.avatar,
-        description: data.description,
-      });
+      setSession(data);
       setCurrentStep("home");
       setStatusMessage(`Welcome back, ${data.handle}!`);
     } catch (error) {
···
 
   async function logout() {
     try {
-      console.log("[useAuth] Cookies before logout:", document.cookie);
       console.log("[useAuth] Starting logout...");
       setStatusMessage("Logging out...");
       await apiClient.logout();
-      console.log("[useAuth] Cookies after logout:", document.cookie);
 
-      apiClient.cache.clear(); // Clear client-side cache
+      apiClient.cache.clear();
       console.log("[useAuth] Cache cleared");
       setSession(null);
       setCurrentStep("login");

src/hooks/useFileUpload.ts

···
-import { parseDataFile } from "../lib/fileExtractor";
+import { parseDataFile } from "../lib/parsers/fileExtractor";
 import type { SearchResult, UserSettings } from "../types";
 
 export function useFileUpload(
···
       return;
     }
 
-    // Initialize search results - convert usernames to SearchResult format
     const initialResults: SearchResult[] = usernames.map((username) => ({
       sourceUser: {
         username: username,

src/hooks/useFollows.ts

···
 import { useState } from "react";
-import { apiClient } from "../lib/apiClient";
-import { FOLLOW_CONFIG } from "../constants/platforms";
-import { ATPROTO_APPS } from "../constants/atprotoApps";
+import { apiClient } from "../lib/api/client";
+import { FOLLOW_CONFIG } from "../config/constants";
+import { getAtprotoApp } from "../lib/utils/platform";
 import type { SearchResult, AtprotoSession, AtprotoAppId } from "../types";
 
 export function useFollow(
···
   ): Promise<void> {
     if (!session || isFollowing) return;
 
-    // Determine source platform for results
-    const followLexicon = ATPROTO_APPS[destinationAppId]?.followLexicon;
-    const destinationName =
-      ATPROTO_APPS[destinationAppId]?.name || "Undefined App";
+    const destinationApp = getAtprotoApp(destinationAppId);
+    const followLexicon =
+      destinationApp?.followLexicon || "app.bsky.graph.follow";
+    const destinationName = destinationApp?.name || "Undefined App";
 
-    if (!followLexicon) {
-      onUpdate(
-        `Error: Invalid destination app or lexicon for ${destinationAppId}`,
-      );
-      return;
-    }
-
-    // Get selected users
     const selectedUsers = searchResults.flatMap((result, resultIndex) =>
       result.atprotoMatches
         .filter((match) => result.selectedMatches?.has(match.did))
···
       return;
     }
 
-    // Check follow status before attempting to follow
     setIsCheckingFollowStatus(true);
     onUpdate(`Checking follow status for ${selectedUsers.length} users...`);
 
···
       followStatusMap = await apiClient.checkFollowStatus(dids, followLexicon);
     } catch (error) {
       console.error("Failed to check follow status:", error);
-      // Continue without filtering - backend will handle duplicates
     } finally {
       setIsCheckingFollowStatus(false);
     }
 
-    // Filter out users already being followed
     const usersToFollow = selectedUsers.filter(
       (user) => !followStatusMap[user.did],
     );
···
         `${alreadyFollowingCount} user${alreadyFollowingCount > 1 ? "s" : ""} already followed. Following ${usersToFollow.length} remaining...`,
       );
 
-      // Update UI to show already followed status
       setSearchResults((prev) =>
         prev.map((result) => ({
           ...result,
···
           totalFollowed += data.succeeded;
           totalFailed += data.failed;
 
-          // Mark successful follows in UI
           data.results.forEach((result) => {
             if (result.success) {
               const user = batch.find((u) => u.did === result.did);
···
                               match.did === result.did
                                 ? {
                                     ...match,
-                                    followed: true, // Backward compatibility
+                                    followed: true,
                                     followStatus: {
                                       ...match.followStatus,
                                       [followLexicon]: true,
···
           totalFailed += batch.length;
           console.error("Batch follow error:", error);
         }
-
-        // Rate limit handling is in the backend
       }
 
       const finalMsg =

src/hooks/useSearch.ts

···
 import { useState } from "react";
-import { apiClient } from "../lib/apiClient";
-import { SEARCH_CONFIG } from "../constants/platforms";
+import { apiClient } from "../lib/api/client";
+import { SEARCH_CONFIG } from "../config/constants";
 import type { SearchResult, SearchProgress, AtprotoSession } from "../types";
 
 export function useSearch(session: AtprotoSession | null) {
···
       const batch = resultsToSearch.slice(i, i + BATCH_SIZE);
       const usernames = batch.map((r) => r.sourceUser.username);
 
-      // Mark current batch as searching
       setSearchResults((prev) =>
         prev.map((result, index) =>
           i <= index && index < i + BATCH_SIZE
···
           followLexicon,
         );
 
-        // Reset error counter on success
         consecutiveErrors = 0;
 
-        // Process batch results
         data.results.forEach((result) => {
           totalSearched++;
           if (result.actors.length > 0) {
···
           `Searched ${totalSearched} of ${resultsToSearch.length} users. Found ${totalFound} matches.`,
         );
 
-        // Update results
-        setSearchResults((prev) =>
-          prev.map((result, index) => {
-            const batchResultIndex = index - i;
-            if (
-              batchResultIndex >= 0 &&
-              batchResultIndex < data.results.length
-            ) {
-              const batchResult = data.results[batchResultIndex];
-              const newSelectedMatches = new Set<string>();
-
-              // Auto-select only the first (highest scoring) match
-              if (batchResult.actors.length > 0) {
-                newSelectedMatches.add(batchResult.actors[0].did);
-              }
-
-              return {
-                ...result,
-                atprotoMatches: batchResult.actors,
-                isSearching: false,
-                error: batchResult.error,
-                selectedMatches: newSelectedMatches,
-              };
-            }
-            return result;
-          }),
-        );
-
         setSearchResults((prev) =>
           prev.map((result, index) => {
             const batchResultIndex = index - i;
···
         console.error("Batch search error:", error);
         consecutiveErrors++;
 
-        // Mark batch as failed
         setSearchResults((prev) =>
           prev.map((result, index) =>
             i <= index && index < i + BATCH_SIZE
···
           ),
         );
 
-        // If we hit rate limits or repeated errors, add exponential backoff
         if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
           const backoffDelay = Math.min(
             1000 * Math.pow(2, consecutiveErrors - MAX_CONSECUTIVE_ERRORS),

src/lib/api/IApiClient.ts

···
+import type {
+  AtprotoSession,
+  BatchSearchResult,
+  BatchFollowResult,
+  SaveResultsResponse,
+  SearchResult,
+} from "../../types";
+
+/**
+ * API Client Interface
+ * Defines the contract that all API implementations must follow
+ **/
+export interface IApiClient {
+  // Authentication
+  startOAuth(handle: string): Promise<{ url: string }>;
+  getSession(): Promise<AtprotoSession>;
+  logout(): Promise<void>;
+
+  // Upload History
+  getUploads(): Promise<{
+    uploads: Array<{
+      uploadId: string;
+      sourcePlatform: string;
+      createdAt: string;
+      totalUsers: number;
+      matchedUsers: number;
+      unmatchedUsers: number;
+    }>;
+  }>;
+
+  getUploadDetails(
+    uploadId: string,
+    page?: number,
+    pageSize?: number,
+  ): Promise<{
+    results: SearchResult[];
+    pagination?: {
+      page: number;
+      pageSize: number;
+      totalPages: number;
+      totalUsers: number;
+      hasNextPage: boolean;
+      hasPrevPage: boolean;
+    };
+  }>;
+
+  getAllUploadDetails(uploadId: string): Promise<{ results: SearchResult[] }>;
+
+  // Search Operations
+  batchSearchActors(
+    usernames: string[],
+    followLexicon?: string,
+  ): Promise<{ results: BatchSearchResult[] }>;
+
+  checkFollowStatus(
+    dids: string[],
+    followLexicon: string,
+  ): Promise<Record<string, boolean>>;
+
+  // Follow Operations
+  batchFollowUsers(
+    dids: string[],
+    followLexicon: string,
+  ): Promise<{
+    success: boolean;
+    total: number;
+    succeeded: number;
+    failed: number;
+    alreadyFollowing: number;
+    results: BatchFollowResult[];
+  }>;
+
+  // Save Results
+  saveResults(
+    uploadId: string,
+    sourcePlatform: string,
+    results: SearchResult[],
+  ): Promise<SaveResultsResponse | null>;
+
+  // Cache management
+  cache: {
+    clear: () => void;
+    invalidate: (key: string) => void;
+    invalidatePattern: (pattern: string) => void;
+  };
+}

src/lib/api/adapters/RealApiAdapter.ts

···
+import type { IApiClient } from "../IApiClient";
+import type {
+  AtprotoSession,
+  BatchSearchResult,
+  BatchFollowResult,
+  SaveResultsResponse,
+  SearchResult,
+} from "../../../types";
+import { CacheService } from "../../../lib/utils/cache";
+import { CACHE_CONFIG } from "../../../config/constants";
+
+/**
+ * Unwrap standardized API response format
+ */
+function unwrapResponse<T>(response: any): T {
+  if (response.success !== undefined && response.data !== undefined) {
+    return response.data as T;
+  }
+  return response as T;
+}
+
+/**
+ * Real API Client Adapter
+ * Implements actual HTTP calls to backend
+ */
+export class RealApiAdapter implements IApiClient {
+  private responseCache = new CacheService(CACHE_CONFIG.DEFAULT_TTL);
+
+  async startOAuth(handle: string): Promise<{ url: string }> {
+    const currentOrigin = window.location.origin;
+
+    const res = await fetch("/.netlify/functions/oauth-start", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        login_hint: handle,
+        origin: currentOrigin,
+      }),
+    });
+
+    if (!res.ok) {
+      const errorData = await res.json();
+      throw new Error(errorData.error || "Failed to start OAuth flow");
+    }
+
+    const response = await res.json();
+    return unwrapResponse<{ url: string }>(response);
+  }
+
+  async getSession(): Promise<AtprotoSession> {
+    const cacheKey = "session";
+    const cached = this.responseCache.get<AtprotoSession>(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const res = await fetch("/.netlify/functions/session", {
+      credentials: "include",
+    });
+
+    if (!res.ok) {
+      throw new Error("No valid session");
+    }
+
+    const response = await res.json();
+    const data = unwrapResponse<AtprotoSession>(response);
+
+    this.responseCache.set(cacheKey, data, CACHE_CONFIG.PROFILE_TTL);
+    return data;
+  }
+
+  async logout(): Promise<void> {
+    const res = await fetch("/.netlify/functions/logout", {
+      method: "POST",
+      credentials: "include",
+    });
+
+    if (!res.ok) {
+      throw new Error("Logout failed");
+    }
+
+    this.responseCache.clear();
+  }
+
+  async getUploads(): Promise<{
+    uploads: Array<{
+      uploadId: string;
+      sourcePlatform: string;
+      createdAt: string;
+      totalUsers: number;
+      matchedUsers: number;
+      unmatchedUsers: number;
+    }>;
+  }> {
+    const cacheKey = "uploads";
+    const cached = this.responseCache.get<any>(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const res = await fetch("/.netlify/functions/get-uploads", {
+      credentials: "include",
+    });
+
+    if (!res.ok) {
+      throw new Error("Failed to fetch uploads");
+    }
+
+    const response = await res.json();
+    const data = unwrapResponse<any>(response);
+
+    this.responseCache.set(cacheKey, data, CACHE_CONFIG.UPLOAD_LIST_TTL);
+    return data;
+  }
+
+  async getUploadDetails(
+    uploadId: string,
+    page: number = 1,
+    pageSize: number = 50,
+  ): Promise<{
+    results: SearchResult[];
+    pagination?: any;
+  }> {
+    const cacheKey = `upload-details-${uploadId}-p${page}-s${pageSize}`;
+    const cached = this.responseCache.get<any>(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const res = await fetch(
+      `/.netlify/functions/get-upload-details?uploadId=${uploadId}&page=${page}&pageSize=${pageSize}`,
+      { credentials: "include" },
+    );
+
+    if (!res.ok) {
+      throw new Error("Failed to fetch upload details");
+    }
+
+    const response = await res.json();
+    const data = unwrapResponse<any>(response);
+
+    this.responseCache.set(cacheKey, data, CACHE_CONFIG.UPLOAD_DETAILS_TTL);
+    return data;
+  }
+
+  async getAllUploadDetails(
+    uploadId: string,
+  ): Promise<{ results: SearchResult[] }> {
+    const firstPage = await this.getUploadDetails(uploadId, 1, 100);
+
+    if (!firstPage.pagination || firstPage.pagination.totalPages === 1) {
+      return { results: firstPage.results };
+    }
+
+    const allResults = [...firstPage.results];
+    const promises = [];
+
+    for (let page = 2; page <= firstPage.pagination.totalPages; page++) {
+      promises.push(this.getUploadDetails(uploadId, page, 100));
+    }
+
+    const remainingPages = await Promise.all(promises);
+    for (const pageData of remainingPages) {
+      allResults.push(...pageData.results);
+    }
+
+    return { results: allResults };
+  }
+
+  async checkFollowStatus(
+    dids: string[],
+    followLexicon: string,
+  ): Promise<Record<string, boolean>> {
+    const cacheKey = `follow-status-${followLexicon}-${dids.slice().sort().join(",")}`;
+    const cached = this.responseCache.get<Record<string, boolean>>(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const res = await fetch("/.netlify/functions/check-follow-status", {
+      method: "POST",
+      credentials: "include",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ dids, followLexicon }),
+    });
+
+    if (!res.ok) {
+      throw new Error("Failed to check follow status");
+    }
+
+    const response = await res.json();
+    const data = unwrapResponse<{ followStatus: Record<string, boolean> }>(
+      response,
+    );
+
+    this.responseCache.set(
+      cacheKey,
+      data.followStatus,
+      CACHE_CONFIG.FOLLOW_STATUS_TTL,
+    );
+    return data.followStatus;
+  }
+
+  async batchSearchActors(
+    usernames: string[],
+    followLexicon?: string,
+  ): Promise<{ results: BatchSearchResult[] }> {
+    const cacheKey = `search-${followLexicon || "default"}-${usernames.slice().sort().join(",")}`;
+    const cached = this.responseCache.get<any>(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const res = await fetch("/.netlify/functions/batch-search-actors", {
+      method: "POST",
+      credentials: "include",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ usernames, followLexicon }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`Batch search failed: ${res.status}`);
+    }
+
+    const response = await res.json();
+    const data = unwrapResponse<{ results: BatchSearchResult[] }>(response);
+
+    this.responseCache.set(cacheKey, data, CACHE_CONFIG.SEARCH_RESULTS_TTL);
+    return data;
+  }
+
+  async batchFollowUsers(
+    dids: string[],
+    followLexicon: string,
+  ): Promise<{
+    success: boolean;
+    total: number;
+    succeeded: number;
+    failed: number;
+    alreadyFollowing: number;
+    results: BatchFollowResult[];
+  }> {
+    const res = await fetch("/.netlify/functions/batch-follow-users", {
+      method: "POST",
+      credentials: "include",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ dids, followLexicon }),
+    });
+
+    if (!res.ok) {
+      throw new Error("Batch follow failed");
+    }
+
+    const response = await res.json();
+    const data = unwrapResponse<any>(response);
+
+    // Invalidate caches after following
+    this.responseCache.invalidate("uploads");
+    this.responseCache.invalidatePattern("upload-details");
+    this.responseCache.invalidatePattern("follow-status");
+
+    return data;
+  }
+
+  async saveResults(
+    uploadId: string,
+    sourcePlatform: string,
+    results: SearchResult[],
+  ): Promise<SaveResultsResponse | null> {
+    try {
+      const resultsToSave = results
+        .filter((r) => !r.isSearching)
+        .map((r) => ({
+          sourceUser: r.sourceUser,
+          atprotoMatches: r.atprotoMatches || [],
+        }));
+
+      const res = await fetch("/.netlify/functions/save-results", {
+        method: "POST",
+        credentials: "include",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          uploadId,
+          sourcePlatform,
+          results: resultsToSave,
+        }),
+      });
+
+      if (res.ok) {
+        const response = await res.json();
+        const data = unwrapResponse<SaveResultsResponse>(response);
+
+        // Invalidate caches
+        this.responseCache.invalidate("uploads");
+        this.responseCache.invalidatePattern("upload-details");
+
+        return data;
+      } else {
+        console.error("Failed to save results:", res.status);
+        return null;
+      }
+    } catch (error) {
+      console.error("Error saving results:", error);
+      return null;
+    }
+  }
+
+  cache = {
+    clear: () => this.responseCache.clear(),
+    invalidate: (key: string) => this.responseCache.delete(key),
+    invalidatePattern: (pattern: string) =>
+      this.responseCache.invalidatePattern(pattern),
+  };
+}

src/lib/api/client.ts

···
+import { IApiClient } from "./IApiClient";
+import { RealApiAdapter } from "./adapters/RealApiAdapter";
+import { MockApiAdapter } from "./adapters/MockApiAdapter";
+import { ENV } from "../../config/env";
+
+/**
+ * API Client Factory
+ * Returns the appropriate implementation based on environment
+ **/
+function createApiClient(): IApiClient {
+  if (ENV.IS_LOCAL_MOCK) {
+    console.log("[API] Using Mock API Adapter");
+    return new MockApiAdapter();
+  }
+
+  console.log("[API] Using Real API Adapter");
+  return new RealApiAdapter();
+}
+
+// Export singleton instance
+export const apiClient = createApiClient();

src/lib/apiClient/index.ts

···
-import { isLocalMockMode } from "../config";
-
-// Import both clients
-import { apiClient as realApiClient } from "./realApiClient";
-import { mockApiClient } from "./mockApiClient";
-
-// Export the appropriate client
-export const apiClient = isLocalMockMode() ? mockApiClient : realApiClient;
-
-// Also export both for explicit usage
-export { realApiClient, mockApiClient };

src/lib/apiClient/mockApiClient.ts src/lib/api/adapters/MockApiAdapter.ts

···
+import type { IApiClient } from "../IApiClient";
 import type {
   AtprotoSession,
   BatchSearchResult,
   BatchFollowResult,
-  SearchResult,
   SaveResultsResponse,
-} from "../../types";
+  SearchResult,
+} from "../../../types";
 
-// Mock user data for testing
 const MOCK_SESSION: AtprotoSession = {
   did: "did:plc:mock123",
   handle: "developer.bsky.social",
···
   description: "Testing ATlast locally",
 };
 
-// Generate mock Bluesky matches
 function generateMockMatches(username: string): any[] {
   const numMatches =
     Math.random() < 0.7 ? Math.floor(Math.random() * 3) + 1 : 0;
···
     postCount: Math.floor(Math.random() * 1000),
     followerCount: Math.floor(Math.random() * 5000),
     followStatus: {
-      "app.bsky.graph.follow": Math.random() < 0.3, // 30% already following
+      "app.bsky.graph.follow": Math.random() < 0.3,
     },
   }));
 }
 
-// Simulate network delay
 const delay = (ms: number = 500) =>
   new Promise((resolve) => setTimeout(resolve, ms));
 
-export const mockApiClient = {
+/**
+ * Mock API Client Adapter
+ * Simulates API responses for local development
+ */
+export class MockApiAdapter implements IApiClient {
   async startOAuth(handle: string): Promise<{ url: string }> {
     await delay(300);
-    console.log("[MOCK] Starting OAuth for:", handle);
-    // In mock mode, just return to home immediately
     return { url: window.location.origin + "/?session=mock" };
-  },
+  }
 
   async getSession(): Promise<AtprotoSession> {
     await delay(200);
-    console.log("[MOCK] Getting session");
 
-    // Check if user has "logged in" via mock OAuth
     const params = new URLSearchParams(window.location.search);
     if (params.get("session") === "mock") {
       return MOCK_SESSION;
     }
 
-    // Check localStorage for mock session
     const mockSession = localStorage.getItem("mock_session");
     if (mockSession) {
       return JSON.parse(mockSession);
     }
 
     throw new Error("No mock session");
-  },
+  }
 
   async logout(): Promise<void> {
     await delay(200);
-    console.log("[MOCK] Logging out");
     localStorage.removeItem("mock_session");
     localStorage.removeItem("mock_uploads");
-  },
+  }
 
   async checkFollowStatus(
     dids: string[],
     followLexicon: string,
   ): Promise<Record<string, boolean>> {
     await delay(300);
-    console.log("[MOCK] Checking follow status for:", dids.length, "DIDs");
 
-    // Mock: 30% chance each user is already followed
     const followStatus: Record<string, boolean> = {};
     dids.forEach((did) => {
       followStatus[did] = Math.random() < 0.3;
     });
 
     return followStatus;
-  },
+  }
 
   async getUploads(): Promise<{ uploads: any[] }> {
     await delay(300);
-    console.log("[MOCK] Getting uploads");
 
     const mockUploads = localStorage.getItem("mock_uploads");
     if (mockUploads) {
···
     }
 
     return { uploads: [] };
-  },
+  }
 
   async getUploadDetails(
     uploadId: string,
     page: number = 1,
     pageSize: number = 50,
-  ): Promise<{
-    results: SearchResult[];
-    pagination?: any;
-  }> {
+  ): Promise<{ results: SearchResult[]; pagination?: any }> {
     await delay(500);
-    console.log("[MOCK] Getting upload details:", uploadId);
 
     const mockData = localStorage.getItem(`mock_upload_${uploadId}`);
     if (mockData) {
···
     }
 
     return { results: [] };
-  },
+  }
 
   async getAllUploadDetails(
     uploadId: string,
   ): Promise<{ results: SearchResult[] }> {
     return this.getUploadDetails(uploadId);
-  },
+  }
 
   async batchSearchActors(
     usernames: string[],
     followLexicon?: string,
   ): Promise<{ results: BatchSearchResult[] }> {
-    await delay(800); // Simulate API delay
-    console.log("[MOCK] Searching for:", usernames);
+    await delay(800);
 
     const results: BatchSearchResult[] = usernames.map((username) => ({
       username,
···
     }));
 
     return { results };
-  },
+  }
 
-  async batchFollowUsers(dids: string[]): Promise<{
+  async batchFollowUsers(
+    dids: string[],
+    followLexicon: string,
+  ): Promise<{
     success: boolean;
     total: number;
     succeeded: number;
     failed: number;
+    alreadyFollowing: number;
     results: BatchFollowResult[];
   }> {
     await delay(1000);
-    console.log("[MOCK] Following users:", dids);
 
     const results: BatchFollowResult[] = dids.map((did) => ({
       did,
···
       total: dids.length,
       succeeded: dids.length,
       failed: 0,
+      alreadyFollowing: 0,
       results,
     };
-  },
+  }
 
   async saveResults(
     uploadId: string,
     sourcePlatform: string,
     results: SearchResult[],
-  ): Promise<SaveResultsResponse> {
+  ): Promise<SaveResultsResponse | null> {
     await delay(500);
-    console.log("[MOCK] Saving results:", {
-      uploadId,
-      sourcePlatform,
-      count: results.length,
-    });
 
-    // Save to localStorage
     localStorage.setItem(`mock_upload_${uploadId}`, JSON.stringify(results));
 
-    // Add to uploads list
     const uploads = JSON.parse(localStorage.getItem("mock_uploads") || "[]");
     const matchedUsers = results.filter(
       (r) => r.atprotoMatches.length > 0,
···
       matchedUsers,
       unmatchedUsers: results.length - matchedUsers,
     };
-  },
+  }
 
-  cache: {
+  cache = {
     clear: () => console.log("[MOCK] Cache cleared"),
     invalidate: (key: string) => console.log("[MOCK] Cache invalidated:", key),
     invalidatePattern: (pattern: string) =>
       console.log("[MOCK] Cache pattern invalidated:", pattern),
-  },
-};
+  };
+}

src/lib/apiClient/realApiClient.ts

···
-import type {
-  AtprotoSession,
-  BatchSearchResult,
-  BatchFollowResult,
-  SaveResultsResponse,
-  SearchResult,
-} from "../../types";
-
-// Client-side cache with TTL
-interface CacheEntry<T> {
-  data: T;
-  timestamp: number;
-}
-
-class ResponseCache {
-  private cache = new Map<string, CacheEntry<any>>();
-  private readonly defaultTTL = 5 * 60 * 1000; // 5 minutes
-
-  set<T>(key: string, data: T, ttl: number = this.defaultTTL): void {
-    this.cache.set(key, {
-      data,
-      timestamp: Date.now(),
-    });
-
-    // Clean up old entries periodically
-    if (this.cache.size > 50) {
-      this.cleanup();
-    }
-  }
-
-  get<T>(key: string, ttl: number = this.defaultTTL): T | null {
-    const entry = this.cache.get(key);
-    if (!entry) return null;
-
-    if (Date.now() - entry.timestamp > ttl) {
-      this.cache.delete(key);
-      return null;
-    }
-
-    return entry.data as T;
-  }
-
-  invalidate(key: string): void {
-    this.cache.delete(key);
-  }
-
-  invalidatePattern(pattern: string): void {
-    for (const key of this.cache.keys()) {
-      if (key.includes(pattern)) {
-        this.cache.delete(key);
-      }
-    }
-  }
-
-  clear(): void {
-    this.cache.clear();
-  }
-
-  private cleanup(): void {
-    const now = Date.now();
-    for (const [key, entry] of this.cache.entries()) {
-      if (now - entry.timestamp > this.defaultTTL) {
-        this.cache.delete(key);
-      }
-    }
-  }
-}
-
-const cache = new ResponseCache();
-
-/**
- * Unwrap the standardized API response format
- * New format: { success: true, data: {...} }
- * Old format: direct data
- */
-function unwrapResponse<T>(response: any): T {
-  if (response.success !== undefined && response.data !== undefined) {
-    return response.data as T;
-  }
-  return response as T;
-}
-
-export const apiClient = {
-  // OAuth and Authentication
-  async startOAuth(handle: string): Promise<{ url: string }> {
-    const currentOrigin = window.location.origin;
-
-    const res = await fetch("/.netlify/functions/oauth-start", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        login_hint: handle,
-        origin: currentOrigin,
-      }),
-    });
-
-    if (!res.ok) {
-      const errorData = await res.json();
-      throw new Error(errorData.error || "Failed to start OAuth flow");
-    }
-
-    const response = await res.json();
-    return unwrapResponse<{ url: string }>(response);
-  },
-
-  async getSession(): Promise<{
-    did: string;
-    handle: string;
-    displayName?: string;
-    avatar?: string;
-    description?: string;
-  }> {
-    // Check cache first
-    const cacheKey = "session";
-    const cached = cache.get<AtprotoSession>(cacheKey);
-    if (cached) {
-      console.log("Returning cached session");
-      return cached;
-    }
-
-    const res = await fetch("/.netlify/functions/session", {
-      credentials: "include",
-    });
-
-    if (!res.ok) {
-      throw new Error("No valid session");
-    }
-
-    const response = await res.json();
-    const data = unwrapResponse<AtprotoSession>(response);
-
-    // Cache the session data for 5 minutes
-    cache.set(cacheKey, data, 5 * 60 * 1000);
-
-    return data;
-  },
-
-  async logout(): Promise<void> {
-    const res = await fetch("/.netlify/functions/logout", {
-      method: "POST",
-      credentials: "include",
-    });
-
-    if (!res.ok) {
-      throw new Error("Logout failed");
-    }
-
-    // Clear all caches on logout
-    cache.clear();
-  },
-
-  // Upload History Operations
-  async getUploads(): Promise<{
-    uploads: Array<{
-      uploadId: string;
-      sourcePlatform: string;
-      createdAt: string;
-      totalUsers: number;
-      matchedUsers: number;
-      unmatchedUsers: number;
-    }>;
-  }> {
-    // Check cache first
-    const cacheKey = "uploads";
-    const cached = cache.get<any>(cacheKey, 2 * 60 * 1000); // 2 minute cache for uploads list
-    if (cached) {
-      console.log("Returning cached uploads");
-      return cached;
-    }
-
-    const res = await fetch("/.netlify/functions/get-uploads", {
-      credentials: "include",
-    });
-
-    if (!res.ok) {
-      throw new Error("Failed to fetch uploads");
-    }
-
-    const response = await res.json();
-    const data = unwrapResponse<any>(response);
-
-    // Cache uploads list for 2 minutes
-    cache.set(cacheKey, data, 2 * 60 * 1000);
-
-    return data;
-  },
-
-  async getUploadDetails(
-    uploadId: string,
-    page: number = 1,
-    pageSize: number = 50,
-  ): Promise<{
-    results: SearchResult[];
-    pagination?: {
-      page: number;
-      pageSize: number;
-      totalPages: number;
-      totalUsers: number;
-      hasNextPage: boolean;
-      hasPrevPage: boolean;
-    };
-  }> {
-    // Check cache first (cache by page)
-    const cacheKey = `upload-details-${uploadId}-p${page}-s${pageSize}`;
-    const cached = cache.get<any>(cacheKey, 10 * 60 * 1000);
-    if (cached) {
-      console.log(
-        "Returning cached upload details for",
-        uploadId,
-        "page",
-        page,
-      );
-      return cached;
-    }
-
-    const res = await fetch(
-      `/.netlify/functions/get-upload-details?uploadId=${uploadId}&page=${page}&pageSize=${pageSize}`,
-      { credentials: "include" },
-    );
-
-    if (!res.ok) {
-      throw new Error("Failed to fetch upload details");
-    }
-
-    const response = await res.json();
-    const data = unwrapResponse<any>(response);
-
-    // Cache upload details page for 10 minutes
-    cache.set(cacheKey, data, 10 * 60 * 1000);
-
-    return data;
-  },
-
-  // Helper to load all pages (for backwards compatibility)
-  async getAllUploadDetails(
-    uploadId: string,
-  ): Promise<{ results: SearchResult[] }> {
-    const firstPage = await this.getUploadDetails(uploadId, 1, 100);
-
-    if (!firstPage.pagination || firstPage.pagination.totalPages === 1) {
-      return { results: firstPage.results };
-    }
-
-    // Load remaining pages
-    const allResults = [...firstPage.results];
-    const promises = [];
-
-    for (let page = 2; page <= firstPage.pagination.totalPages; page++) {
-      promises.push(this.getUploadDetails(uploadId, page, 100));
-    }
-
-    const remainingPages = await Promise.all(promises);
-    for (const pageData of remainingPages) {
-      allResults.push(...pageData.results);
-    }
-
-    return { results: allResults };
-  },
-
-  // NEW: Check follow status
-  async checkFollowStatus(
-    dids: string[],
-    followLexicon: string,
-  ): Promise<Record<string, boolean>> {
-    // Check cache first
-    const cacheKey = `follow-status-${followLexicon}-${dids.slice().sort().join(",")}`;
-    const cached = cache.get<Record<string, boolean>>(cacheKey, 2 * 60 * 1000); // 2 minute cache
-    if (cached) {
-      console.log("Returning cached follow status");
-      return cached;
-    }
-
-    const res = await fetch("/.netlify/functions/check-follow-status", {
-      method: "POST",
-      credentials: "include",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ dids, followLexicon }),
-    });
-
-    if (!res.ok) {
-      throw new Error("Failed to check follow status");
-    }
-
-    const response = await res.json();
-    const data = unwrapResponse<{ followStatus: Record<string, boolean> }>(
-      response,
-    );
-
-    // Cache for 2 minutes
-    cache.set(cacheKey, data.followStatus, 2 * 60 * 1000);
-
-    return data.followStatus;
-  },
-
-  // Search Operations
-  async batchSearchActors(
-    usernames: string[],
-    followLexicon?: string,
-  ): Promise<{ results: BatchSearchResult[] }> {
-    // Create cache key from sorted usernames (so order doesn't matter)
-    const cacheKey = `search-${followLexicon || "default"}-${usernames.slice().sort().join(",")}`;
-    const cached = cache.get<any>(cacheKey, 10 * 60 * 1000);
-    if (cached) {
-      console.log(
-        "Returning cached search results for",
-        usernames.length,
-        "users",
-      );
-      return cached;
-    }
-
-    const res = await fetch("/.netlify/functions/batch-search-actors", {
-      method: "POST",
-      credentials: "include",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ usernames, followLexicon }),
-    });
-
-    if (!res.ok) {
-      throw new Error(`Batch search failed: ${res.status}`);
-    }
-
-    const response = await res.json();
-    const data = unwrapResponse<{ results: BatchSearchResult[] }>(response);
-
-    // Cache search results for 10 minutes
-    cache.set(cacheKey, data, 10 * 60 * 1000);
-
-    return data;
-  },
-
-  // Follow Operations
-  async batchFollowUsers(
-    dids: string[],
-    followLexicon: string,
-  ): Promise<{
-    success: boolean;
-    total: number;
-    succeeded: number;
-    failed: number;
-    alreadyFollowing: number;
-    results: BatchFollowResult[];
-  }> {
-    const res = await fetch("/.netlify/functions/batch-follow-users", {
-      method: "POST",
-      credentials: "include",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ dids, followLexicon }),
-    });
-
-    if (!res.ok) {
-      throw new Error("Batch follow failed");
-    }
-
-    const response = await res.json();
-    const data = unwrapResponse<any>(response);
-
-    // Invalidate caches after following
-    cache.invalidate("uploads");
-    cache.invalidatePattern("upload-details");
-    cache.invalidatePattern("follow-status");
-
-    return data;
-  },
-
-  // Save Results
-  async saveResults(
-    uploadId: string,
-    sourcePlatform: string,
-    results: SearchResult[],
-  ): Promise<SaveResultsResponse | null> {
-    try {
-      const resultsToSave = results
-        .filter((r) => !r.isSearching)
-        .map((r) => ({
-          sourceUser: r.sourceUser,
-          atprotoMatches: r.atprotoMatches || [],
-        }));
-
-      console.log(`Saving ${resultsToSave.length} results in background...`);
-
-      const res = await fetch("/.netlify/functions/save-results", {
-        method: "POST",
-        credentials: "include",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          uploadId,
-          sourcePlatform,
-          results: resultsToSave,
-        }),
-      });
-
-      if (res.ok) {
-        const response = await res.json();
-        const data = unwrapResponse<SaveResultsResponse>(response);
-        console.log(`Successfully saved ${data.matchedUsers} matches`);
-
-        // Invalidate caches after saving
-        cache.invalidate("uploads");
-        cache.invalidatePattern("upload-details");
-
-        return data;
-      } else {
-        console.error("Failed to save results:", res.status, await res.text());
-        return null;
-      }
-    } catch (error) {
-      console.error(
-        "Error saving results (will continue in background):",
-        error,
-      );
-      return null;
-    }
-  },
-
-  // Cache management utilities
-  cache: {
-    clear: () => cache.clear(),
-    invalidate: (key: string) => cache.invalidate(key),
-    invalidatePattern: (pattern: string) => cache.invalidatePattern(pattern),
-  },
-};

src/lib/config.ts

···
-export const ENV = {
-  // Detect if we're in local mock mode
-  IS_LOCAL_MOCK: import.meta.env.VITE_LOCAL_MOCK === "true",
-
-  // API base URL
-  API_BASE: import.meta.env.VITE_API_BASE || "/.netlify/functions",
-
-  // Feature flags
-  ENABLE_OAUTH: import.meta.env.VITE_ENABLE_OAUTH !== "false",
-  ENABLE_DATABASE: import.meta.env.VITE_ENABLE_DATABASE !== "false",
-} as const;
-
-export function isLocalMockMode(): boolean {
-  return ENV.IS_LOCAL_MOCK;
-}
-
-export function getApiUrl(endpoint: string): string {
-  return `${ENV.API_BASE}/${endpoint}`;
-}

src/lib/utils/cache.ts

···
+/**
+ * Generic client-side cache with TTL support
+ * Used for simple caching needs on the frontend
+ **/
+export class CacheService<T = any> {
+  private cache = new Map<string, { value: T; expires: number }>();
+  private readonly defaultTTL: number;
+
+  constructor(defaultTTLMs: number = 5 * 60 * 1000) {
+    this.defaultTTL = defaultTTLMs;
+  }
+
+  set(key: string, value: T, ttlMs?: number): void {
+    const ttl = ttlMs ?? this.defaultTTL;
+    this.cache.set(key, {
+      value,
+      expires: Date.now() + ttl,
+    });
+
+    if (this.cache.size > 100) {
+      this.cleanup();
+    }
+  }
+
+  get<U = T>(key: string): U | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+
+    if (Date.now() > entry.expires) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.value as U;
+  }
+
+  has(key: string): boolean {
+    return this.get(key) !== null;
+  }
+
+  delete(key: string): void {
+    this.cache.delete(key);
+  }
+
+  invalidatePattern(pattern: string): void {
+    for (const key of this.cache.keys()) {
+      if (key.includes(pattern)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expires) {
+        this.cache.delete(key);
+      }
+    }
+  }
+}

src/lib/utils/date.ts

···
+export function formatDate(dateString: string): string {
+  const date = new Date(dateString);
+  return date.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+export function formatRelativeTime(dateString: string): string {
+  const date = new Date(dateString);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+  const diffDays = Math.floor(diffMs / 86400000);
+
+  if (diffMins < 1) return "just now";
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 7) return `${diffDays}d ago`;
+
+  return formatDate(dateString);
+}

src/lib/utils/platform.ts

···
-import { PLATFORMS, type PlatformConfig } from "../../constants/platforms";
-import { ATPROTO_APPS, type AtprotoApp } from "../../constants/atprotoApps";
+import { PLATFORMS, type PlatformConfig } from "../../config/platforms";
+import { ATPROTO_APPS, type AtprotoApp } from "../../config/atprotoApps";
 import type { AtprotoAppId } from "../../types/settings";
 
 /**

src/pages/Home.tsx

···
 import UploadTab from "../components/UploadTab";
 import HistoryTab from "../components/HistoryTab";
 import PlaceholderTab from "../components/PlaceholderTab";
-import { apiClient } from "../lib/apiClient";
+import { apiClient } from "../lib/api/client";
 import type { Upload as UploadType } from "../types";
 import type { UserSettings } from "../types/settings";
 import SettingsPage from "./Settings";

src/pages/Settings.tsx

···
 import { Settings as SettingsIcon, ChevronRight } from "lucide-react";
-import { PLATFORMS } from "../constants/platforms";
-import { ATPROTO_APPS } from "../constants/atprotoApps";
+import { PLATFORMS } from "../config/platforms";
+import { ATPROTO_APPS } from "../config/atprotoApps";
 import type { UserSettings, PlatformDestinations } from "../types/settings";
 
 interface SettingsPageProps {

src/types/auth.types.ts

···
-// Authentication and session types
-
 export interface AtprotoSession {
   did: string;
   handle: string;

src/types/common.types.ts

···
-// Common shared types
-
 export type AppStep =
   | "checking"
   | "login"

src/types/index.ts

···
-// Session and Auth Types
 export * from "./auth.types";
-
-// Search and Match Types
 export * from "./search.types";
-
-// Common Types
 export * from "./common.types";
 
 // Re-export settings types for convenience