Santa's logistics operations platform for global gift delivery

ICBG is a full-stack application that combines an interactive 3D globe interface with AI-powered gift recommendations to help Santa efficiently dispatch gifts to households worldwide. The platform identifies addresses within user-selected areas, intelligently pairs appropriate gifts using AI, and manages the entire order lifecycle.

• 🌍 Interactive Globe Interface - Draw polygons on a 3D globe to select delivery areas
• 🏠 Real-time Address Identification - Fetch building addresses from OpenStreetMap Overpass API
• 🤖 AI-Powered Gift Pairing - Intelligent gift recommendations based on household metadata (powered by Grok-4)
• 📧 Email Notifications - Festive delivery notifications via AgentMail MCP server
• 🛒 Automated Purchasing - Direct product purchasing via Shopping Agent MCP server
• 📦 Order Management - Create, track, and export delivery batches
• 🎨 Festive Dark Theme - Holiday-themed UI with shadcn/ui components

• Node.js 22.x LTS
• npm or pnpm
• Mapbox account (for access token)
• Convex account (for database)
• Dedalus Labs API key (for AI features)

1. Clone the repository:

git clone https://github.com/yourusername/ICBG.git
cd ICBG

2. Install dependencies:

npm install

3. Set up environment variables:

cp .env.example .env.local

Edit .env.local with your API keys:

# Mapbox access token for globe visualization
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.xxx

# Convex deployment URL (auto-populated by `npx convex dev`)
NEXT_PUBLIC_CONVEX_URL=https://xxx.convex.cloud

# Dedalus Labs API key for AI gift pairing and MCP server access
DEDALUS_API_KEY=sk-xxx

4. Initialize Convex:

npx convex dev

This will:

• Create a new Convex project
• Deploy the schema and functions
• Populate NEXT_PUBLIC_CONVEX_URL in .env.local

5. Start the development servers:

npm run dev

The app will be available at http://localhost:3000.

icbg/
├── app/                    # Next.js App Router pages
│   ├── api/               # API route handlers
│   │   ├── addresses/     # Address identification (Overpass API)
│   │   ├── catalog/       # Product catalog browsing
│   │   ├── gifts/         # AI gift pairing
│   │   ├── notifications/ # Email notifications (AgentMail MCP)
│   │   └── orders/        # Order export & purchase (Shopping Agent MCP)
│   ├── orders/            # Order history page (SSR with Convex)
│   └── page.tsx           # Main mission control
├── components/            # React components
│   ├── ui/               # shadcn/ui components
│   ├── GlobeMap/         # Map, markers, and drawing components
│   ├── ControlPanel/     # Sidebar workflow controls
│   └── OrderHistory/     # Order batch management
├── convex/               # Convex database
│   ├── schema.ts         # Database schema (batches, orders, selections)
│   ├── orderBatches.ts   # Batch CRUD operations
│   ├── orders.ts         # Order CRUD operations
│   └── addressSelections.ts # Selection history
├── lib/                  # Utility libraries
│   ├── types.ts          # TypeScript type definitions
│   ├── overpass.ts       # OSM Overpass API client
│   ├── dedalus.ts        # Dedalus SDK (AI + MCP orchestration)
│   ├── agentmail.ts      # Email notification helpers
│   ├── mapbox.ts         # Mapbox GL configuration
│   └── utils.ts          # General utilities
└── data/
    └── catalog.json      # Product catalog (20 items, 5 categories)

1. Select Area - Click "Select Area" (or press D) and draw a polygon on the globe
2. Review Addresses - View identified addresses with household metadata
3. Pair Gifts - Use AI or manual strategy to assign gifts
4. Send Notifications - (Optional) Send festive delivery emails
5. Buy Products - (Optional) Automated purchasing via Shopping Agent MCP
6. Confirm Orders - Create batch in database
7. Export - Download CSV/JSON manifest

The application leverages the following MCP (Model Context Protocol) servers via Dedalus Labs:

Gift pairing and agent orchestration use the xai/grok-4-fast-non-reasoning model via the Dedalus Labs SDK.

# Run development servers (Next.js + Convex in parallel)
npm run dev

# Type check
npm run type-check

# Lint
npm run lint

# Format code with Prettier
npm run format

# Build for production
npm run build

# Deploy Convex to production
npm run convex:deploy

MIT License - see LICENSE for details.

• OpenStreetMap contributors for address data
• Mapbox for the globe visualization
• Dedalus Labs for AI/MCP integration
• shadcn for the beautiful UI components

🎄 Built with ❤️ for the Holiday Season 2025