Battlemap

Google Earth for Companies - A viral, visually stunning 3D map of the business world.

🌟 Overview

Battlemap is a free-to-explore, competitive intelligence tool that visualizes the entire business landscape in stunning 3D. Users can:

• Explore industries as glowing galaxy clusters
• Drill down into categories with smooth 3D transitions
• Discover companies visualized as buildings with real-time data
• Generate battle cards for competitive analysis (soft-gated)
• Share beautiful visual snapshots across social media

Live Demo: battlemaps.io (coming soon)

🎯 Key Features

Visual Architecture

🌌 Galaxy View (Zoomed Out)

• Industries rendered as particle nebulae using InstancedMesh
• Golden spiral layout algorithm for natural distribution
• Background star field (2,000 particles)
• Bloom post-processing for glow effects
• Idle auto-rotation with dampened user controls

🏙️ Landscape View (Drilled In)

• Companies as 3D buildings with logos (BrandFetch integration)
• Building height scales logarithmically with market cap
• Category zones with color-coded boundaries
• Spring physics animations for building transitions
• OrbitControls for pan/zoom/rotate

🔄 Smooth Transitions

• Galaxy → Landscape: ~1.5s choreographed animation
  1. Cluster glow (200ms)
  2. Other clusters fade (300ms)
  3. Camera fly-to (500ms, easeInOutCubic)
  4. Particles coalesce (300ms)
  5. Buildings rise (staggered 50ms each, spring physics)
  6. Labels fade in (200ms)

Progressive Enhancement

📱 2D Mobile Fallback

• Automatic device capability detection (3 tiers: high/mid/low)
• Graceful fallback for:
  • No WebGL support
  • Low-end mobile devices
  • Users preferring reduced motion
• IndustryGrid: Card-based industry browser
• CompanyList: Searchable company list with metrics

♿ Accessibility

• Keyboard navigation (Escape to close panels)
• Reduced motion support
• ARIA labels and semantic HTML
• Screen reader friendly

🏗️ Architecture

Technology Stack

Project Structure

apps/battlemap/
├── app/
│   ├── layout.tsx                 # Root layout, metadata
│   ├── page.tsx                   # Landing page with BattlemapView
│   ├── industry/[slug]/
│   │   └── page.tsx              # Industry detail page
│   ├── company/[slug]/
│   │   └── page.tsx              # Company profile page
│   ├── compare/[slugs]/
│   │   └── page.tsx              # Company comparison page
│   └── alternatives/[slug]/
│       └── page.tsx              # Alternatives page
│
├── components/
│   ├── BattlemapView.tsx         # Main orchestrator (3D/2D, galaxy/landscape)
│   ├── CompanyDetailPanel.tsx    # Slide-in company detail
│   │
│   ├── GalaxyView/
│   │   ├── GalaxyCanvas.tsx      # Galaxy scene container
│   │   ├── IndustryCluster.tsx   # Particle-based industry clusters
│   │   ├── StarField.tsx         # Background stars
│   │   ├── TransitionManager.tsx # Galaxy→Landscape choreography
│   │   ├── types.ts              # Galaxy view types
│   │   └── index.ts
│   │
│   └── MobileView/
│       ├── IndustryGrid.tsx      # 2D industry cards
│       ├── CompanyList.tsx       # 2D company list
│       └── index.ts
│
├── utils/
│   └── deviceCapability.ts       # Device tier detection
│
├── next.config.js                # Next.js config, image domains
├── package.json                  # Dependencies, scripts
└── tsconfig.json                 # TypeScript config

Shared UI Components

Located in packages/ui/src/modules/battlemap/:

packages/ui/src/modules/battlemap/
├── types.ts                      # Shared types (BattlemapCompany, etc.)
├── index.ts                      # Barrel exports
│
└── landscape/
    ├── PublicLandscape3D.tsx     # 3D landscape scene
    ├── CompanyBlock3D.tsx        # Company building blocks
    └── CategoryZone3D.tsx        # Category zone overlays

🚀 Getting Started

Prerequisites

• Node.js 22.x (or compatible version)
• pnpm 10.x
• Supabase account (for database)
• BrandFetch API key (optional, for company logos)

Installation

# From monorepo root
pnpm install

# Build all dependencies
pnpm build

Environment Variables

Create .env.local in monorepo root:

# Supabase (required)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# BrandFetch (optional, for logos)
NEXT_PUBLIC_BRANDFETCH_CLIENT_ID=your-client-id

# PostHog (optional, for analytics)
NEXT_PUBLIC_POSTHOG_KEY=your-posthog-key
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

Database Setup

Run the Supabase migration:

# Apply migration
supabase db push

# Or if using Supabase CLI
supabase migration up

This creates the battlemap schema with:

• industries - Industry metadata
• sectors - Sector groupings
• categories - Category groupings
• companies - Company profiles
• user_profiles - User contribution tracking
• live_views - Real-time viewer counts
• report_generations - Battle card usage tracking

Development

# Run battlemap app only
pnpm --filter @hivebase/battlemap dev

# Or from apps/battlemap directory
cd apps/battlemap
pnpm dev

Visit http://localhost:3002

Build

# Build battlemap
pnpm --filter @hivebase/battlemap build

# Build entire monorepo
pnpm build

📊 Data Model

Core Entities

Industry

interface Industry {
  id: string;
  slug: string;
  name: string;
  color: string;          // Hex color for cluster
  companyCount: number;
  position: { x: number; y: number; z: number };
}

Company (Battlemap)

interface BattlemapCompany {
  id: string;
  slug: string;
  name: string;
  website?: string;
  logoUrl?: string;

  // Positioning (0-100 percentage scale)
  position: { x: number; y: number };

  // Grouping
  categoryId?: string;
  industryId?: string;

  // Public profile
  pitch?: string;
  targetMarket?: string;

  // Visual weight
  marketCap?: number;
  employeeCount?: number;
  fundingStage?: string;

  // Competitive intel
  strengths?: string[];
  weaknesses?: string[];
}

Category

interface BattlemapCategory {
  id: string;
  slug: string;
  name: string;
  color?: string;

  // Visual grouping (0-100 percentage scale)
  position?: { x: number; y: number };
  width?: number;
  height?: number;
}

🎨 Design System

Color Palette

const INDUSTRY_COLORS = {
  technology: "#6366f1",   // Indigo
  finance: "#22c55e",      // Green
  healthcare: "#ec4899",   // Pink
  consumer: "#f59e0b",     // Amber
  energy: "#14b8a6",       // Teal
  industrials: "#8b5cf6",  // Purple
  materials: "#78716c",    // Stone
  utilities: "#06b6d4",    // Cyan
  realestate: "#f97316",   // Orange
  telecom: "#3b82f6",      // Blue
};

Interaction Patterns

Animation Philosophy

"Awe First, Utility Second"

• Prioritize visual impact over information density
• 60fps animations always (degrade quality before frame rate)
• Reward exploration with satisfying micro-interactions
• Never use jarring transitions

🔌 API Integration

Data Sources

1. HiveBase Deep Research API

Primary source for initial data seeding (200-500 companies).

// Future implementation
const companies = await deepResearch({
  industry: "technology",
  category: "crm",
  limit: 50,
});

2. Community Contributions

Users can add companies with AI verification.

// POST /api/companies
{
  name: "Acme Corp",
  website: "https://acme.com",
  industry: "technology",
  // AI verifies legitimacy via Tavily/Exa
}

3. Self-Submission

Companies can claim and enhance their profiles.

// POST /api/companies/claim
{
  companyId: "comp-123",
  verificationMethod: "domain",  // DNS TXT record
}

Battle Card Generation

// POST /api/reports/generate
{
  companyId: "comp-123",
  competitors: ["comp-456", "comp-789"],
}

// Soft-gated: Free account required
// Rate limit: 3 reports/month for free users

🧪 Testing

Device Capability Detection

Test different tiers by forcing view mode:

// Force 3D view
<BattlemapView forceViewMode="3d" />

// Force 2D fallback
<BattlemapView forceViewMode="2d" />

Performance Targets

🚢 Deployment

Vercel (Recommended)

# Deploy to production
vercel --prod

# Preview deployment
vercel

Domain: battlemaps.io

Environment Variables (Production)

Set in Vercel dashboard:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• NEXT_PUBLIC_BRANDFETCH_CLIENT_ID
• NEXT_PUBLIC_POSTHOG_KEY
• NEXT_PUBLIC_POSTHOG_HOST

CDN & Caching

• Static assets: Vercel Edge Network
• BrandFetch logos: cdn.brandfetch.io
• OG images: @vercel/og (edge function)

📈 Analytics & Metrics

Viral Metrics (Primary)

Conversion Metrics

Tracking Events

// PostHog events
posthog.capture('industry_clicked', { industry: 'technology' });
posthog.capture('company_viewed', { company: 'salesforce' });
posthog.capture('report_generated', { company: 'hubspot' });
posthog.capture('share_clicked', { type: 'company_card' });

🛣️ Roadmap

Phase 1: Foundation ✅

• Next.js app scaffold
• Database schema
• Galaxy view with particle clusters
• Landscape view with buildings
• Galaxy → Landscape transitions
• Company detail panel
• 2D mobile fallback

Phase 2: Data & Auth (In Progress)

• Supabase Auth setup
• Company verification API (AI-based)
• Seed initial company data (200+ companies)
• Battle card generation API

Phase 3: Viral Mechanics

• OG image generation for sharing
• Social proof indicators (live viewers)
• Contributor leaderboards
• Company claim flow
• Embeddable widgets

Phase 4: SEO & Growth

• Programmatic page generation (ISR)
• Comparison pages (/compare/x-vs-y)
• Alternatives pages (/alternatives/x)
• Industry trend pages
• Email alerts for followed companies

Phase 5: Monetization

• Soft-gate battle card generation
• HiveBase upsell integration
• API access for power users
• White-label licensing

🤝 Contributing

Code Style

• Follow existing patterns in the codebase
• Use TypeScript for all new code
• Follow CLAUDE.md conventions
• Use meaningful variable names (isTransitioning, not flag)
• Add comments for complex logic

Component Guidelines

3D Components:

• Use useFrame for animations
• Clean up on unmount (timeouts, subscriptions)
• Optimize with useMemo for expensive calculations
• Use Suspense for lazy-loaded assets

2D Components:

• Use Tailwind utility classes
• Avoid inline styles unless dynamic
• Follow accessibility best practices
• Test on mobile devices

Performance

• Lazy load 3D components with Suspense
• Use React.memo for pure components
• Debounce search inputs
• Implement infinite scroll for long lists
• Monitor bundle size with next/bundle-analyzer

🐛 Troubleshooting

Common Issues

"WebGL not supported"

• Ensure device has WebGL capabilities
• Check if hardware acceleration is enabled
• Fallback to 2D view should be automatic

"Logos not loading"

• Check NEXT_PUBLIC_BRANDFETCH_CLIENT_ID is set
• Verify domain is whitelisted in BrandFetch
• Check CORS configuration in next.config.js

"Transition feels janky"

• Check FPS in DevTools (should be 60fps desktop, 30fps mobile)
• Reduce particle count for mid-tier devices
• Disable bloom for low-tier devices

"Build fails"

• Run pnpm install to sync dependencies
• Check Node.js version (should be 22.x)
• Clear .next folder and rebuild
• Check TypeScript errors with pnpm type-check

Debug Mode

Enable debug logging:

// In BattlemapView.tsx, uncomment:
console.log('[BATTLEMAP] Device capability detected:', recommended);
console.log('[BATTLEMAP] Generate report for:', company.name);

📄 License

Proprietary - HiveBase Inc.

For licensing inquiries: contact@hivebase.com

🙏 Acknowledgments

• Three.js - Amazing 3D library
• React Three Fiber - Declarative Three.js wrapper
• Vercel - Deployment platform
• Supabase - Database & auth
• BrandFetch - Company logos

📞 Support

• Documentation: battlemaps.io/docs (coming soon)
• Issues: GitHub Issues
• Discord: HiveBase Community
• Email: support@battlemaps.io

Built with ❤️ by the HiveBase team