Environment Variables

Complete reference for configuring Argument Cartographer environment variables

Overview

Argument Cartographer requires multiple environment variables for AI services, external APIs, and Firebase configuration. This guide provides a complete reference extracted from the actual codebase.

Never commit .env files to version control. Use Vercel’s environment variable settings for production deployments.

Environment File Structure

Create a .env file in your project root:

.env

# AI Configuration
GOOGLE_GENAI_API_KEY=your_gemini_key_here

# External Tools
FIRECRAWL_API_KEY=your_firecrawl_key_here
TWITTER_BEARER_TOKEN=your_twitter_bearer_token_here

# Firebase Client Config (Public)
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_bucket.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# Firebase Admin Config (Server-side)
SERVICE_ACCOUNT_PROJECT_ID=your_project_id
SERVICE_ACCOUNT_CLIENT_EMAIL=firebase-adminsdk@your_project.iam.gserviceaccount.com
SERVICE_ACCOUNT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour_Private_Key_Here\n-----END PRIVATE KEY-----\n"

Variable Reference

AI Configuration

GOOGLE_GENAI_API_KEY · string · required

Google Gemini API Key for AI-powered argument analysis.

• Used in: All AI flows (blueprint generation, fallacy detection, summarization)
• Model: Gemini 1.5 Pro
• Get key: Google AI Studio

The application requires a valid API key. Missing or invalid keys will cause all AI flows to fail.

External API Tools

FIRECRAWL_API_KEY · string · required

Firecrawl API Key for web scraping and search functionality.

• Used in: web-search.ts, web-scraper.ts
• Purpose: Scrapes article content and performs web searches
• Limit: 20 results per search, 20,000 characters per scrape
• Get key: Firecrawl

Error handling:

if (!firecrawlKey || firecrawlKey === 'YOUR_API_KEY_HERE') {
  throw new Error('Firecrawl API key not configured. Please set FIRECRAWL_API_KEY in .env');
}

If Firecrawl fails or credits are depleted, the application falls back to using user query only with limited analysis mode.

TWITTER_BEARER_TOKEN · string · required

Twitter API v2 Bearer Token for social media sentiment analysis.

• Used in: twitter-search.ts for Social Pulse feature
• Query format: {query} lang:en -is:retweet
• Max results: 20 tweets, sorted by relevancy
• Get token: Twitter Developer Portal

Required expansions:

• author_id - Get full user objects
• tweet.fields: created_at, author_id, public_metrics
• user.fields: profile_image_url, username, name

Twitter search failures are non-fatal. The application continues without social pulse data if the API fails.

Firebase Client Configuration

These variables are public (prefixed with NEXT_PUBLIC_) and exposed to the browser:

NEXT_PUBLIC_FIREBASE_API_KEY · string · required

Firebase Web API key for client-side authentication.

Location: Firebase Console → Project Settings → General → Web API Key

NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN · string · required

Firebase authentication domain.

Format: {project-id}.firebaseapp.com

NEXT_PUBLIC_FIREBASE_PROJECT_ID · string · required

Unique Firebase project identifier.

Used in: Client SDK initialization, Firestore paths

NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET · string · required

Firebase Storage bucket name.

Format: {project-id}.appspot.com

NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID · string · required

Firebase Cloud Messaging sender ID for push notifications.

NEXT_PUBLIC_FIREBASE_APP_ID · string · required

Unique Firebase app identifier.

Format: 1:xxxxx:web:xxxxxx

Firebase Admin Configuration

These variables are private (server-side only) and used for admin operations:

SERVICE_ACCOUNT_PROJECT_ID · string · required

Firebase project ID for admin SDK.

Must match: NEXT_PUBLIC_FIREBASE_PROJECT_ID

SERVICE_ACCOUNT_CLIENT_EMAIL · string · required

Service account email for Firebase Admin SDK.

Format: firebase-adminsdk-{id}@{project-id}.iam.gserviceaccount.com

Location: Firebase Console → Project Settings → Service Accounts → Generate new private key

SERVICE_ACCOUNT_PRIVATE_KEY · string · required

Service account private key for server-side Firebase operations.

Format: Must be enclosed in double quotes with escaped newlines:

"-----BEGIN PRIVATE KEY-----\nYour_Key_Here\n-----END PRIVATE KEY-----\n"

Critical Security Note:

• Keep this key secret and never expose it in client-side code
• In Vercel, paste the entire key including quotes and newlines
• Rotation recommended every 90 days

Validation and Error Handling

The application validates environment variables at runtime:

API Key Validation

// Firecrawl validation (web-search.ts:55-59)
if (!firecrawlKey || firecrawlKey === 'YOUR_API_KEY_HERE') {
  throw new Error('Firecrawl API key not configured. Please set FIRECRAWL_API_KEY in .env');
}

// Twitter validation (twitter-search.ts:46-50)
if (!bearerToken || bearerToken === 'YOUR_BEARER_TOKEN_HERE') {
  throw new Error('TWITTER_BEARER_TOKEN is not configured. Please add it to your .env file.');
}

Fallback Behavior

Firecrawl API Failure

When Firecrawl API fails or credits are depleted:

1. Application attempts fallback to general search without site filtering
2. If all scraping fails, uses search snippets as context
3. If search also fails, enters limited analysis mode using only the user query

// From generate-argument-blueprint.ts:242-253
console.warn("[Flow] No external sources available (API credits may be depleted). Using user query only.");
isLimitedAnalysis = true;
context = `
--- USER QUERY (No External Sources Available) ---
Topic: ${input.input}

NOTE: External search APIs are unavailable. Generate an analysis based solely on your training knowledge about this topic.
`;

Twitter API Failure

Twitter search failures are non-fatal:

// From generate-argument-blueprint.ts:337-339
catch (error: any) {
  console.error("Twitter search failed, continuing. Error:", error.message);
}

The application continues without social pulse data and returns an empty tweets array.

Security Best Practices

1. Never Commit Secrets

   Add .env to .gitignore:

   .gitignore

   .env
   .env.local
   .env*.local
   
2. Use Vercel Environment Variables

   For production, add variables in:

   Vercel Dashboard → Project Settings → Environment Variables

   Set scope:

   • Production: Live environment
   • Preview: Pull request previews
   • Development: Local development (optional)
3. Rotate Keys Regularly

   • Firebase service account keys: Every 90 days
   • API keys: When team members leave
   • Immediately if keys are exposed
4. Use Separate Environments

   Maintain separate Firebase projects and API keys for:

   • Development
   • Staging
   • Production

Testing Configuration

Verify your environment variables are loaded correctly:

// Check if variables are available
console.log('Firebase Config:', {
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  hasApiKey: !!process.env.GOOGLE_GENAI_API_KEY,
  hasFirecrawl: !!process.env.FIRECRAWL_API_KEY,
  hasTwitter: !!process.env.TWITTER_BEARER_TOKEN,
});

Never log actual API keys or secrets to the console in production.

Troubleshooting

Environment variables not loading in Vercel

Solution:

1. Verify variables are added in Vercel dashboard
2. Check variable scope (Production/Preview/Development)
3. Redeploy after adding new variables
4. Ensure NEXT_PUBLIC_ prefix for client-side variables

Firebase authentication not working

Check:

• All 6 NEXT_PUBLIC_FIREBASE_* variables are set
• Auth domain matches Firebase console
• Service account private key format (escaped newlines)

API calls failing with 401/403 errors

Check:

• API keys are valid and not expired
• Keys don’t have placeholder values like YOUR_API_KEY_HERE
• Billing is enabled for paid APIs
• Rate limits not exceeded

Next Steps

Firebase Setup

Configure Firebase project and security rules

Vercel Deployment

Deploy your application to production

API Errors

Debug API integration issues

Common Issues

Resolve common deployment problems