Last updated: Aug 4, 2025, 11:26 AM UTC

External Service Prerequisites Validation - Build v3

Status: Phase 0 Prerequisites Validation
Priority: BLOCKING - Required before any development
Framework: v3 Lesson #1 - API Keys Must Be Available Before Starting Development
Date: August 3, 2025

Phase 0 Validation Overview

Critical Requirement (v2 Lesson #1)

"Cannot proceed with AI integration without OpenRouter API keys configured"
Impact: BLOCKING - Development stops completely until external service access is secured

Validation Scope

All external service credentials must be gathered, validated, and functional before any development begins. This prevents the v2 issue where development had to stop due to missing API access.

External Service Prerequisites Checklist

AI Services MANDATORY

OpenRouter (Primary AI Provider) - v2 Lesson #2

  • Account Creation: OpenRouter account established
  • API Key Generation: Production-ready API key obtained
  • Credit/Billing Setup: Sufficient credits or billing configured
  • Rate Limits Verified: Understanding of rate limits and costs
  • Model Access: Confirm access to required models (Claude, GPT-4, etc.)
  • Integration Testing: Basic API connectivity test successful

Why OpenRouter Priority: v2 Lesson #2 - "OpenRouter provides better abstraction vs OpenAI direct integration"

Anthropic (Fallback AI Provider)

  • Account Creation: Anthropic account established
  • API Key Generation: Claude API access configured
  • Credit/Billing Setup: Billing configured for fallback usage
  • Rate Limits Understanding: Backup provider capacity planning
  • Integration Preparation: Fallback integration pattern prepared

Email Services

Postmark (Email Delivery)

  • Account Creation: Postmark account established
  • Domain Verification: Production domain added and verified
  • DKIM/SPF Records: DNS records configured for deliverability
  • API Key Generation: Server API key obtained
  • Sender Signatures: From addresses configured and verified
  • Delivery Testing: Test email sending functional

Database Services

Database Choice Validation (v2 Lesson #12)

  • Database Decision: Supabase vs Local PostgreSQL choice made
  • Account Setup: Production database account configured (if Supabase)
  • Connection String: Database connection validated
  • Schema Planning: Multi-tenant architecture planned
  • Backup Strategy: Data backup and recovery planned

Deployment Services

Production Hosting

  • Platform Choice: Vercel/Railway/AWS deployment platform selected
  • Account Setup: Production hosting account configured
  • Domain Configuration: Custom domain ready for deployment
  • Environment Variables: Production environment variable strategy
  • Monitoring Setup: Error tracking and performance monitoring planned

Payment Services (If Subscription Model)

  • Stripe Account: Payment processing account configured
  • API Keys: Live and test API keys obtained
  • Webhook Endpoints: Payment webhook handling planned
  • Tax Configuration: Tax calculation setup if required
  • Compliance: Payment security compliance validated

Service Validation Tests

AI Service Connectivity

# OpenRouter API validation
curl -X POST "https://openrouter.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3-sonnet-20240229",
    "messages": [{"role": "user", "content": "Test connection"}]
  }'

# Anthropic API validation  
curl -X POST "https://api.anthropic.com/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Test connection"}]
  }'

Email Service Validation

# Postmark API validation
curl -X POST "https://api.postmarkapp.com/email" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: $POSTMARK_SERVER_TOKEN" \
  -d '{
    "From": "test@yourdomain.com",
    "To": "test@yourdomain.com",
    "Subject": "API Validation Test",
    "TextBody": "Testing Postmark API connectivity"
  }'

Database Connectivity

// Database connection validation
import { createClient } from '@supabase/supabase-js'
// or PostgreSQL direct connection

const testDatabaseConnection = async () => {
  try {
    // Test connection and basic query
    const result = await db.query('SELECT NOW()');
    console.log('Database connected:', result);
    return true;
  } catch (error) {
    console.error('Database connection failed:', error);
    return false;
  }
};

Service Configuration Documentation

Environment Variables Template

# AI Services
OPENROUTER_API_KEY=your_openrouter_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Email Services  
POSTMARK_SERVER_TOKEN=your_postmark_server_token_here
POSTMARK_FROM_EMAIL=your_verified_sender@yourdomain.com

# Database
DATABASE_URL=your_database_connection_string_here
DATABASE_PASSWORD=your_database_password_here

# Deployment
VERCEL_TOKEN=your_vercel_token_here
NEXT_PUBLIC_APP_URL=https://your-production-domain.com

# Payment (if applicable)
STRIPE_SECRET_KEY=your_stripe_secret_key_here
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret_here

Service Access Documentation

## Service Access Guide

### OpenRouter
- **Dashboard**: https://openrouter.ai/keys
- **Documentation**: https://openrouter.ai/docs
- **Models**: Claude-3-Sonnet, GPT-4, etc.
- **Rate Limits**: [Document specific limits]

### Anthropic
- **Console**: https://console.anthropic.com/
- **Documentation**: https://docs.anthropic.com/
- **Models**: Claude-3-Sonnet-20240229
- **Rate Limits**: [Document specific limits]

### Postmark
- **Dashboard**: https://postmarkapp.com/
- **Domain Setup**: [Your domain verification status]
- **DKIM/SPF**: [DNS record configuration]
- **Delivery Stats**: [Monitor deliverability]

### Database
- **Type**: [Supabase/PostgreSQL]
- **Dashboard**: [Database admin URL]
- **Backup**: [Backup strategy and schedule]
- **Monitoring**: [Performance monitoring setup]

Validation Results

Service Readiness Status

AI Services READY

  • OpenRouter: Primary AI provider configured with API key (following v2 Lesson #2)
  • Anthropic: Fallback provider configured with Claude API access
  • Cost Planning: Development API keys configured for testing

Email Services READY

  • Postmark: Server token configured for email delivery
  • Domain Configuration: nudgecampaign.com domain configured
  • From Email: hello@nudgecampaign.com sender configured

Infrastructure Services READY

  • Database: Local PostgreSQL configured with multi-tenant schema
  • Development Environment: Local setup complete with Docker
  • Next.js Configuration: App configured for localhost:3001
  • Authentication: JWT and NextAuth configured for development

Development Services READY

  • Local Development: Complete environment configured
  • Database Schema: Multi-tenant schema ready
  • API Configuration: All required APIs configured
  • Environment Variables: Complete .env configuration validated

Blocking Issues Resolution

Common Issues and Solutions

AI Service Issues

## Issue: OpenRouter API Key Not Working
**Symptoms**: 401 Unauthorized responses
**Solution**: 
1. Verify API key copied correctly
2. Check account billing status
3. Confirm rate limits not exceeded
4. Test with curl command provided above

## Issue: Anthropic API Access Denied
**Symptoms**: Model access restricted
**Solution**:
1. Verify account approval status
2. Check API key permissions
3. Confirm model availability
4. Contact Anthropic support if needed

Email Service Issues

## Issue: Postmark Domain Not Verified
**Symptoms**: Cannot send emails from domain
**Solution**:
1. Complete domain verification process
2. Add required DNS records (DKIM/SPF)
3. Wait for DNS propagation (up to 24 hours)
4. Test with verified sender signature

## Issue: Email Delivery Issues
**Symptoms**: Emails not reaching recipients
**Solution**:
1. Check spam folder and deliverability
2. Verify DKIM/SPF records correct
3. Monitor Postmark delivery statistics
4. Review sender reputation

Phase 0 Completion Criteria

Prerequisites Met REQUIRED FOR PROGRESSION

  • All API Keys Obtained: OpenRouter, Anthropic, Postmark, Database, Hosting
  • Service Connectivity Validated: All APIs responding successfully
  • Production Setup Complete: Domain, DNS, hosting account configured
  • Environment Variables Documented: Complete .env template ready
  • Service Access Guide: Admin URLs and access documentation complete
  • Backup Plans: Fallback strategies for service failures prepared

Quality Gates Passed VALIDATION

  • No Missing Dependencies: All required services available
  • Cost Planning Complete: Budget and usage limits understood
  • Security Validated: API keys and access properly secured
  • Documentation Complete: Service access and configuration documented
  • Escalation Plan: Support contacts and issue resolution paths identified

Next Phase Preparation

Phase 0.1: Design System Implementation (Ready to Begin)

With external services validated, Phase 0.1 can begin:

  • shadcn/ui component library setup
  • CSS variables and design tokens
  • AI-first conversational interface components
  • WCAG AA contrast validation
  • Professional layout standards

Development Environment Ready

  • All API keys available for integration
  • External services responding and functional
  • Production deployment path validated
  • Monitoring and error tracking prepared
  • Service documentation complete for team access

Phase 0 External Service Prerequisites validation ensures development can proceed without service dependency blockers, preventing the v2 issue where missing API access stopped development progress.