Skip to main content

​
System Architecture

Argument Cartographer follows a Modern Monolithic architecture pattern using Next.js 15, optimized for server-side rendering (SSR) and Edge interactions. This design prioritizes simplicity, security, and performance while maintaining the flexibility to scale.
Philosophy: Build monolithic first, extract microservices only when necessary. This keeps the codebase maintainable while allowing future scaling.

​
Architecture Diagram

​
Layer Breakdown

​
1. Client Layer (Frontend)

Technology: Next.js 15 App Router, React 18, TypeScript Responsibilities:
  • User interface rendering
  • Client-side state management
  • Visualization rendering (React Flow, Recharts)
  • Export functionality (html-to-image)
  • Authentication state (Firebase Auth)
Key Files: 
src/app/
  ├── page.tsx                 # Homepage
  ├── dashboard/page.tsx       # Main analysis interface
  ├── radar/page.tsx           # Narrative Radar feed
  └── analysis/[id]/page.tsx   # Individual analysis view

src/components/
  ├── analysis/               # Visualization components
  ├── ui/                     # Shadcn UI primitives
  └── layout/                 # Layout components
Server Components by Default: Next.js 15 uses React Server Components, reducing client-side JavaScript bundle size.

​
2. Intelligence Layer (AI Orchestration)

Technology: Google Genkit, Gemini 1.5 Pro, TypeScript Responsibilities:
  • AI flow orchestration
  • Prompt management
  • Tool execution (web search, scraping, social listening)
  • Response validation and parsing
Key Files: 
src/ai/
  ├── genkit.ts               # Genkit configuration
  ├── flows/
  │   ├── generate-argument-blueprint.ts
  │   ├── identify-logical-fallacies.ts
  │   ├── summarize-source-text.ts
  │   ├── explain-logical-fallacy.ts
  │   └── ask-more.ts
  └── tools/
      ├── web-search.ts
      ├── web-scraper.ts
      └── twitter-search.ts
Execution Environment:
  • Development: Node.js server
  • Production: Vercel serverless functions (with 60s timeout)

​
3. Data Layer (Backend)

Technology: Firebase Firestore, Firebase Auth, Firebase Admin SDK Responsibilities:
  • User authentication and session management
  • Analysis persistence
  • User data isolation
  • Security rules enforcement
Data Structure: 
/users/{userId}
  - id, email, displayName, createdAt
  
  /argumentMaps/{mapId}
    - id, userId, input, blueprint, credibilityScore, fallacies, tweets, createdAt
  
  /sources/{sourceId}
    - id, userId, url, content, scrapedAt

/radarTopics/{topicId}
  - id, title, description, blueprint, credibilityScore, createdAt, updatedAt
Security Model: All user data is isolated under /users/{userId} with path-based authorization. No cross-user data access is allowed.

​
4. External Integration Layer

Services:
  • Firecrawl API: Web search and article scraping
  • Twitter API v2: Social sentiment analysis
  • Google Gemini: LLM inference
Resilience:
  • Graceful degradation if APIs fail
  • Fallback strategies (snippets instead of full scrapes)
  • Clear error messages to users

​
Data Flow

​
Complete Analysis Flow

1

User Submits Topic

User enters topic in dashboard, submits form
<form action={analyzeTopicAction}>
  <input name="topic" />
  <button type="submit">Analyze</button>
</form>
2

Server Action Triggered

Next.js Server Action executes on server
export async function analyzeTopicAction(formData: FormData) {
  const topic = formData.get('topic') as string;
  // ... validation
}
3

Genkit Flow Invoked

Server Action calls Genkit flow
const result = await generateArgumentBlueprint({ input: topic });
4

AI Processing

Genkit orchestrates:
  • Search query generation (Gemini)
  • Web search (Firecrawl)
  • Article scraping (Firecrawl/custom)
  • Twitter search (Twitter API)
  • Argument analysis (Gemini)
  • Fallacy detection (Gemini)
  • Social pulse generation (Gemini)
5

Schema Validation

Result validated with Zod schemas
GenerateArgumentBlueprintOutputSchema.parse(result);
6

Firestore Persistence

Analysis saved to user’s collection
await addDoc(collection(db, `users/${userId}/argumentMaps`), {
  ...result,
  userId,
  createdAt: serverTimestamp(),
});
7

Client Rendering

Server Action returns, client re-renders with data
<AnalysisView analysisData={result} />

​
Scalability Considerations

​
Current Capacity

Estimate: 100-500 simultaneous analysesBottleneck: Gemini API rate limits (60 RPM on free tier)Mitigation: Implement queue system, user-level rate limiting

​
Future Scaling Strategies

Caching Layer

Cache common queries, scraped sources, and search results in Redis/Firestore

Background Jobs

Move analysis to queue (Bull/BullMQ) for async processing

CDN for Radar

Serve Radar topics via CDN with edge caching

Microservices Extraction

Extract scraper and fallacy detection to separate services

​
Security Architecture

​
Authentication Flow

​
Security Layers

1

Client-Side (Firebase Auth)

  • Email/password authentication
  • Session management via cookies
  • Protected routes via middleware
2

Middleware (next-firebase-auth-edge)

  • Token verification on every request
  • Redirect unauthenticated users
  • Extract user claims
3

Server-Side (Firebase Admin)

  • Server Actions verify user identity
  • Database queries filtered by userId
  • No cross-user data exposure
4

Database (Firestore Rules)

  • Path-based authorization
  • Owner-only read/write
  • No public data enumeration

​
Performance Optimization

​
Bundle Size Optimization

module.exports = {
  compiler: {
    removeConsole: process.env.NODE_ENV === 'production',
  },
  experimental: {
    optimizePackageImports: [
      'lucide-react',
      'recharts',
      '@radix-ui/react-*',
    ],
  },
};
Results:
  • Main bundle: ~120KB gzipped
  • First Load JS: 145KB average
  • Code splitting per route

​
Database Optimization

  • Indexes: Created on userId, createdAt for fast queries
  • Composite Indexes: (userId, createdAt) for history views
  • Denormalization: User data duplicated in analysis docs for fast reads

​
Edge Caching

  • Static Pages: Homepage, marketing pages (CDN cached)
  • Dynamic Pages: Dashboard, analysis views (no cache)
  • API Routes: None (all Server Actions)

​
Monitoring & Observability

​
Planned Implementation

Error Tracking

Sentry for client and server error monitoring

Analytics

Vercel Analytics for performance, PostHog for product analytics

Logging

Structured logging with Pino, log aggregation in Datadog/LogRocket

Uptime Monitoring

UptimeRobot or Pingdom for availability checks

​
Technology Choices Rationale

  • Server Components: Reduced JS bundle, better SEO
  • Server Actions: Type-safe RPC without API routes
  • App Router: Modern routing with layouts
  • Vercel Deployment: First-class hosting integration
  • TypeScript: Type safety across stack
  • AI-First Framework: Purpose-built for LLM apps
  • Tool Support: Built-in tool calling patterns
  • Type Safety: Full TypeScript support
  • Observability: Trace logging out of the box
  • Gemini Integration: Native Google AI support
  • Rapid Development: Auth + DB in one SDK
  • Security Rules: Declarative, auditable access control
  • Real-time: Live updates (future feature)
  • Scalability: Managed service, auto-scaling
  • Cost: Free tier generous, pay-as-you-go
  • Quality: Better than raw scraping libraries
  • Reliability: Handles anti-bot measures
  • Markdown Output: Clean, parseable content
  • Rate Limits: Generous free tier
  • Search + Scrape: Combined functionality

​
Next Steps

AI Orchestration

Deep dive into Genkit flows and AI architecture

Data Layer

Firestore schema and security rules explained

External Integrations

How we integrate Firecrawl, Twitter, and Gemini APIs

Installation

Set up your own instance

Build docs developers (and LLMs) love

Get started for freeTalk to us