Installation

Overview

Argument Cartographer is built as a modern Next.js 15 application with server-side AI orchestration. This guide covers everything from local development to production deployment.

This guide is for developers who want to run their own instance. End users should use the hosted version at [your-domain.com]

Prerequisites

Before you begin, ensure you have:

Node.js 18+

Download from nodejs.org

Git

Version control - git-scm.com

Firebase Project

Create at console.firebase.google.com

API Keys

Google GenAI, Firecrawl, Twitter Bearer Token

System Requirements

OS: macOS, Linux, or Windows (WSL2 recommended)
RAM: Minimum 8GB (16GB recommended)
Disk Space: 2GB for dependencies and build artifacts
Internet: Required for AI API calls

Step 1: Clone the Repository

First, clone the project from GitHub:

git clone https://github.com/BHARTIYAYASH/ARGX.git
cd ARGX

If you’re forking the project, replace the URL with your fork’s repository URL.

Step 2: Install Dependencies

Install all required npm packages:

npm install

Key Dependencies

The installation includes:

Next.js 15 - React framework with App Router
Firebase - Authentication and Firestore database
Genkit - AI orchestration framework
React Flow - Interactive graph visualization
Tailwind CSS - Utility-first styling
Radix UI - Accessible component primitives

Installation typically takes 2-5 minutes depending on your internet speed.

Step 3: Configure Environment Variables

Create a .env file in the project root with all required API keys and configuration.

Create .env File

cp .env.example .env

Required Environment Variables

AI Configuration
External Tools
Firebase Client
Firebase Admin

# Google Gemini AI API Key
GOOGLE_GENAI_API_KEY=your_gemini_api_key_here

How to obtain:

Visit Google AI Studio
Create a new API key
Copy and paste into .env

Free tier includes 60 requests per minute - sufficient for development.

# Firecrawl Web Search & Scraping
FIRECRAWL_API_KEY=your_firecrawl_api_key

# Twitter/X API Bearer Token
TWITTER_BEARER_TOKEN=your_twitter_bearer_token

Firecrawl Setup:

Sign up at firecrawl.dev
Get API key from dashboard
Free tier: 500 requests/month

Twitter Setup:

Apply for Twitter Developer account at developer.twitter.com
Create a new app
Generate Bearer Token from app settings
Copy Bearer Token (starts with AAAA...)

# Firebase Client SDK Configuration
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_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789
NEXT_PUBLIC_FIREBASE_APP_ID=1:123:web:abc123

How to obtain:

Go to Firebase Console
Select your project
Click ⚙️ Settings → Project settings
Scroll to “Your apps” section
Click the “Web app” icon
Copy the config values

# Firebase Admin SDK (Server-Side)
SERVICE_ACCOUNT_PROJECT_ID=your_project_id
SERVICE_ACCOUNT_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your_project.iam.gserviceaccount.com
SERVICE_ACCOUNT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour\nPrivate\nKey\nHere\n-----END PRIVATE KEY-----\n"

How to obtain:

Firebase Console → Project Settings
Go to Service accounts tab
Click Generate new private key
Download JSON file
Extract values:
- project_id → SERVICE_ACCOUNT_PROJECT_ID
- client_email → SERVICE_ACCOUNT_CLIENT_EMAIL
- private_key → SERVICE_ACCOUNT_PRIVATE_KEY (keep \n characters)

Keep the private key secure! Never commit it to version control.

Complete .env Example

# AI Configuration
GOOGLE_GENAI_API_KEY=AIzaSy...

# External Tools
FIRECRAWL_API_KEY=fc-...
TWITTER_BEARER_TOKEN=AAAAAAAAAAAAA...

# Firebase Client Config
NEXT_PUBLIC_FIREBASE_API_KEY=AIzaSyD...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=myproject.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=myproject-abc123
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=myproject-abc123.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789012
NEXT_PUBLIC_FIREBASE_APP_ID=1:123:web:abc123def456

# Firebase Admin Config
SERVICE_ACCOUNT_PROJECT_ID=myproject-abc123
SERVICE_ACCOUNT_CLIENT_EMAIL=firebase-adminsdk-xxxxx@myproject.iam.gserviceaccount.com
SERVICE_ACCOUNT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBg...\n-----END PRIVATE KEY-----\n"

Step 4: Set Up Firebase

Configure Firebase Authentication and Firestore database.

Enable Authentication

Navigate to Authentication

Firebase Console → Build → Authentication

Get Started

Click Get started button

Enable Email/Password

Click Email/Password provider
Toggle Enable
Save changes

(Optional) Add Other Providers

You can also enable:

Google Sign-In
GitHub
Twitter

Set Up Firestore Database

Navigate to Firestore

Firebase Console → Build → Firestore Database

Create Database

Click Create database

Choose Mode

Select Production mode (we’ll add custom rules next)

Select Location

Choose a region close to your users (e.g., us-central1)

Deploy Security Rules

The project includes comprehensive Firestore security rules in firestore.rules:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    
    // Helper: Check if user is authenticated
    function isSignedIn() {
      return request.auth != null;
    }
    
    // Helper: Check ownership
    function isOwner(userId) {
      return isSignedIn() && request.auth.uid == userId;
    }
    
    // User profiles
    match /users/{userId} {
      allow get: if isOwner(userId);
      allow list: if false; // Prevent user enumeration
      allow create: if isOwner(userId);
      allow update, delete: if isOwner(userId);
    }
    
    // Argument maps (private to user)
    match /users/{userId}/argumentMaps/{mapId} {
      allow read, write: if isOwner(userId);
    }
    
    // Sources (private to user)
    match /users/{userId}/sources/{sourceId} {
      allow read, write: if isOwner(userId);
    }
  }
}

Deploy rules:

# Install Firebase CLI if not already installed
npm install -g firebase-tools

# Login
firebase login

# Deploy rules only
firebase deploy --only firestore:rules

The security model ensures strict user data isolation - each user can only access their own data.

Step 5: Run Development Server

Start the local development server with hot reload:

npm run dev

The application will start on http://localhost:9002 (custom port to avoid conflicts).

The development server uses Turbopack for faster builds and hot module replacement.

Verify Installation

Open your browser and navigate to:

http://localhost:9002 - Homepage should load
http://localhost:9002/login - Login page with Firebase auth
http://localhost:9002/dashboard - Should redirect to login (requires auth)

Step 6: Test AI Flows (Optional)

Genkit provides a development UI to test AI flows independently:

npm run genkit:dev

This opens a web interface at http://localhost:4000 where you can:

Test generateArgumentBlueprint flow
Test identifyLogicalFallacies flow
Test webSearch and twitterSearch tools
View trace logs and performance metrics

The Genkit dev server runs separately from the Next.js app - you can run both simultaneously.

Step 7: Build for Production

Create an optimized production build:

NODE_ENV=production npm run build

Build Output

You’ll see output like:

✓ Compiled successfully
✓ Collecting page data
✓ Generating static pages (12/12)
✓ Collecting build traces
✓ Finalizing page optimization

Route (app)                              Size     First Load JS
┌ ○ /                                    5.2 kB         120 kB
├ ○ /dashboard                           8.1 kB         145 kB
├ ○ /login                               3.4 kB         118 kB
└ ○ /analysis/[id]                      12.3 kB         158 kB

First Load JS sizes include shared chunks. Individual routes are optimized via code splitting.

Start Production Server

npm run start

The production server runs on http://localhost:3000 by default.

Troubleshooting

Module Not Found Errors

Problem: Error: Cannot find module 'xyz'Solution:

# Clear node_modules and reinstall
rm -rf node_modules
npm install

Firebase Auth Errors

Problem: Firebase: Error (auth/invalid-api-key)Solution:

Verify all NEXT_PUBLIC_FIREBASE_* variables in .env
Check that API key matches Firebase Console
Ensure no extra quotes or spaces in .env values

Genkit API Errors

Problem: Error: GOOGLE_GENAI_API_KEY is not setSolution:

Verify GOOGLE_GENAI_API_KEY in .env
Check that the key is valid in Google AI Studio
Restart dev server after adding the key

Build Fails with TypeScript Errors

Problem: Type errors during npm run buildSolution:

# Run type check independently
npm run typecheck

# Fix reported errors, then rebuild
npm run build

Port Already in Use

Problem: Error: listen EADDRINUSE: address already in use :::9002Solution:

# Find and kill process using port 9002
lsof -ti:9002 | xargs kill

# Or change port in package.json:
# "dev": "next dev -p 3000"

Next Steps

Configuration

Customize settings and features

Deploy to Vercel

Deploy to production

Architecture

Understand the system design

API Reference

Explore the API surface

Overview

Getting Started

Core Features

User Guide

Architecture

Overview

Prerequisites

Node.js 18+

Git

Firebase Project

API Keys

System Requirements

Step 1: Clone the Repository

Step 2: Install Dependencies

Key Dependencies

Step 3: Configure Environment Variables

Create .env File

Required Environment Variables

Complete .env Example

Step 4: Set Up Firebase

Enable Authentication

Set Up Firestore Database

Deploy Security Rules

Step 5: Run Development Server

Verify Installation

Step 6: Test AI Flows (Optional)

Step 7: Build for Production

Build Output

Start Production Server

Troubleshooting

Next Steps

Configuration

Deploy to Vercel

Architecture

API Reference

Build docs developers (and LLMs) love

Overview

Getting Started

Core Features

User Guide

Architecture

​Overview

​Prerequisites

Node.js 18+

Git

Firebase Project

API Keys

​System Requirements

​Step 1: Clone the Repository

​Step 2: Install Dependencies

​Key Dependencies

​Step 3: Configure Environment Variables

​Create .env File

​Required Environment Variables

​Complete .env Example

​Step 4: Set Up Firebase

​Enable Authentication

​Set Up Firestore Database

​Deploy Security Rules

​Step 5: Run Development Server

​Verify Installation

​Step 6: Test AI Flows (Optional)

​Step 7: Build for Production

​Build Output

​Start Production Server

​Troubleshooting

​Next Steps

Configuration

Deploy to Vercel

Architecture

API Reference

Build docs developers (and LLMs) love

Overview

Prerequisites

System Requirements

Step 1: Clone the Repository

Step 2: Install Dependencies

Key Dependencies

Step 3: Configure Environment Variables

Create .env File

Required Environment Variables

Complete .env Example

Step 4: Set Up Firebase

Enable Authentication

Set Up Firestore Database

Deploy Security Rules

Step 5: Run Development Server

Verify Installation

Step 6: Test AI Flows (Optional)

Step 7: Build for Production

Build Output

Start Production Server

Troubleshooting

Next Steps