Our Tech Stack

This guide explains the tools we use and why we chose them. Understanding the "why" helps you make good decisions when building new features.

Core principle: Choose boring technology for infrastructure, innovative technology for features.

The Stack at a Glance

┌─────────────────────────────────────────────────────────────┐
│                        FRONTEND                              │
│  NextJS + Tailwind CSS + Shadcn UI                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        BACKEND                               │
│  NextJS API Routes (simple) │ FastAPI (ML/AI heavy)         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       DATABASE                               │
│  Supabase (PostgreSQL + Auth + Realtime + Storage)          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    EXTERNAL SERVICES                         │
│  Claude/OpenAI │ DataForSEO │ SerpAPI │ Google APIs         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      DEPLOYMENT                              │
│  Railway (hosting) + Cloudflare (domains/CDN)               │
└─────────────────────────────────────────────────────────────┘

Frontend

NextJS

What it is: React framework with built-in routing, server-side rendering, and API routes.

Why we use it:

• Full-stack in one project (frontend + API)
• Great developer experience
• Large ecosystem and community
• Works well with Claude Code (lots of training data)

When to use NextJS API routes vs FastAPI:

Tailwind CSS

What it is: Utility-first CSS framework.

Why we use it:

• Consistent styling without writing custom CSS
• Fast iteration (change styles in HTML, not separate files)
• Works perfectly with component libraries
• AI understands it well

Shadcn UI

What it is: Collection of reusable components built on Radix UI.

Why we use it:

• Not a dependency — components are copied into your project
• Fully customizable
• Accessible by default
• Consistent design language

Key insight: Shadcn is not installed via npm. You run npx shadcn-ui@latest add button to add components to your project.

Backend

NextJS API Routes

What it is: Backend endpoints that live alongside your frontend.

Why we use it:

• Same deployment as frontend
• Shared types between frontend and backend
• Simple for straightforward operations

FastAPI (Python)

What it is: Modern Python web framework for building APIs.

Why we use it:

• Python is required for ML libraries (scikit-learn, HDBSCAN)
• Automatic API documentation
• Great async support for parallel API calls
• Type hints for better AI code generation

Our pattern: NextJS frontend calls FastAPI backend for ML-heavy operations.

User → NextJS Frontend → NextJS API → FastAPI → ML Processing
                                   ↓
                              Return results

Database

Supabase

What it is: Open-source Firebase alternative built on PostgreSQL.

Why we use it:

• Real PostgreSQL (not proprietary)
• Built-in authentication
• Real-time subscriptions
• Row-level security
• Storage for files
• Generous free tier

Key features we use:

better-auth

What it is: Authentication library for TypeScript.

Why we use it over Supabase Auth:

• More flexible
• Works with any database
• Better session management
• Easier to customize

AI & Machine Learning

Claude (Anthropic)

What it is: Large language model API.

Why we use it:

• Best at following complex instructions
• Excellent at code generation
• Strong reasoning capabilities
• Our primary LLM for agents

OpenAI

What it is: LLM and embeddings API.

Why we use it:

• Best embedding models (text-embedding-3-small)
• Widely supported
• Reliable and fast

Our pattern: OpenAI for embeddings, Claude for generation.

Agent Frameworks

We use multiple approaches for building agents:

SEO Data Providers

DataForSEO

What it is: API for SERP data, rankings, and SEO metrics.

Why we use it:

• Comprehensive SERP data
• AI Overviews data
• Competitive pricing
• Good documentation

SerpAPI

What it is: Google Search API.

Why we use it:

• Simpler than DataForSEO for basic searches
• Pay-per-use pricing
• Multiple search engines

Deployment

Railway

What it is: Platform-as-a-Service for deployment.

Why we use it:

• Deploy from GitHub with zero config
• Supports NextJS, FastAPI, PostgreSQL
• Automatic HTTPS
• Environment variable management
• Reasonable pricing

Deployment pattern:

GitHub Push → Railway detects → Builds → Deploys → Live

Cloudflare

What it is: DNS, CDN, and domain management.

Why we use it:

• Fast DNS propagation
• DDoS protection
• Free SSL
• Caching for static assets

Development Tools

Claude Code

What it is: AI coding assistant in terminal/VS Code.

Why we use it:

• Understands full project context
• Can read/write files directly
• Executes commands
• Our primary development partner

See How We Code with AI for workflows.

Git + GitHub

What it is: Version control and code hosting.

Why we use it:

• Industry standard
• Great collaboration features
• GitHub Actions for CI/CD
• Issue tracking

See Version Control and GitHub for details.

Choosing Technologies for New Projects

Decision Framework

When starting a new project, ask:

1. Is it a web app? → Start with NextJS + Supabase + Tailwind + Shadcn
2. Does it need ML? → Add FastAPI backend
3. Does it need an AI agent? → Add Claude API + memory storage
4. Does it need SEO data? → Add DataForSEO or SerpAPI

Default Stack for Each Product Type

Quick Reference