API Versioning & AWS Migration Plan¶
Date: 2025-12-13 Objective: Prepare Vell for partner/agentic co-sell integrations while achieving 100% AWS deployed status Context: AWS Marketplace partners seeking programmatic integration for co-sell capabilities
Executive Summary¶
This plan addresses two strategic initiatives:
- API Versioning - Future-proof the API for partner and AWS programmatic integrations
- AWS Migration - Complete the remaining ~5% to achieve 100% AWS deployed status
What Counts Against "100% AWS Deployed"¶
| Service Type | Counts? | Rationale |
|---|---|---|
| Core compute/storage | ✅ Yes | Control plane services |
| AI/ML engines | ✅ Yes | Application data processing |
| Real-time/messaging | ✅ Yes | Application infrastructure |
| Error tracking | ✅ Yes | Operational tooling |
| Payment gateways | ❌ No | Required external (Stripe, PayPal) |
| Social OAuth | ❌ No | Required external (Google, Facebook) |
| CRM (HubSpot) | ❌ No | External data enrichment |
| Search enrichment (Serper) | ❌ No | External data source |
| Marketing automation (Kajabi) | ❌ No | Front-end system |
Current State¶
- AWS Compliance Progress: ~65% (per existing removal plan)
- API Versioning: None (all routes at
/api/*) - HubSpot Integration: Basic contacts only
Part 1: API Versioning Strategy¶
1.1 Why Version Now?¶
Your agentic co-sell capability will mature toward: - Partner integrations - AWS ISV partners programmatically querying/updating listings - AWS integrations - Marketplace APIs, APN co-sell automation - Agent-to-agent - AI agents orchestrating workflows across systems
Versioning now means you can evolve without breaking existing consumers.
1.2 Recommended Approach: URL-Based Versioning¶
Current: /api/auth/login
Future: /api/v1/auth/login ← Frozen baseline
/api/v2/auth/login ← Breaking changes
Why URL-based (not header-based): - Explicit and discoverable - Easy to test (just change URL) - Works well with API Gateway - Standard for AWS APIs
1.3 Implementation Structure¶
routes/
├── api.php # Legacy routes (deprecated, redirects to v1)
├── api_v1.php # Version 1 routes (current functionality)
└── api_v2.php # Version 2 routes (future)
app/Http/Controllers/Api/
├── V1/ # Version 1 controllers
│ ├── AuthController.php
│ ├── AIChatController.php
│ ├── AIWriterController.php
│ ├── MarketplaceController.php # NEW: Partner APIs
│ └── ...
└── V2/ # Future version
1.4 Partner API Endpoints (New for v1)¶
For co-sell and AWS Marketplace partner integration:
# Partner Authentication
POST /api/v1/partners/auth/token # OAuth2 client credentials
# Listing Management
GET /api/v1/partners/listings # List partner's listings
GET /api/v1/partners/listings/{id} # Get listing details
PUT /api/v1/partners/listings/{id} # Update listing
GET /api/v1/partners/listings/{id}/seo # Get SEO score/recommendations
# Co-Sell Operations
GET /api/v1/partners/cosell/opportunities # List co-sell opportunities
POST /api/v1/partners/cosell/opportunities # Create opportunity
PATCH /api/v1/partners/cosell/opportunities/{id} # Update opportunity
# Analytics
GET /api/v1/partners/analytics/summary # Dashboard metrics
GET /api/v1/partners/analytics/reports # Detailed reports
# Webhooks (outbound)
POST /api/v1/webhooks/configure # Set up webhook endpoints
GET /api/v1/webhooks/events # List available events
1.5 API Gateway Integration¶
Deploy API Gateway in front of Laravel for partner APIs:
┌─────────────────────────────────────────────────────────────┐
│ API GATEWAY (REST) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ /api/v1/* │ │ /api/v2/* │ │ /partners/webhooks │ │
│ │ (Public) │ │ (Future) │ │ (Outbound events) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
│ │ │ │ │
│ ┌──────┴───────────────┴───────────────────┴──────┐ │
│ │ API Gateway Features │ │
│ │ • Rate limiting (by partner) │ │
│ │ • API key management │ │
│ │ • Request/response logging │ │
│ │ • WAF integration │ │
│ │ • Usage plans & quotas │ │
│ └──────────────────────┬──────────────────────────┘ │
└─────────────────────────┼───────────────────────────────────┘
│
▼
┌───────────────────────┐
│ ALB → EC2 │
│ Laravel Backend │
└───────────────────────┘
1.6 Versioning Policy¶
| Version | Status | Support |
|---|---|---|
| v1 | Current | Full support, bug fixes |
| v2 | Future | Breaking changes go here |
Unversioned /api/* |
Deprecated | Redirect to v1, sunset after 6 months |
Part 2: AWS Migration (Remaining ~5%)¶
2.1 Services to Migrate¶
Based on your clarification and existing compliance plan:
| Current Service | AWS Replacement | Priority | Effort |
|---|---|---|---|
| Pusher | API Gateway WebSocket | High | Medium |
| Sentry | CloudWatch + X-Ray | High | Low |
| Direct AI APIs | Bedrock only | Medium | Medium |
2.2 Pusher → API Gateway WebSocket¶
Current Usage:
- Real-time chat streaming
- Live updates in UI
- File: config/broadcasting.php (Pusher as default)
Migration Path:
┌─────────────────────────────────────────────────────────────┐
│ API GATEWAY WEBSOCKET │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Routes: │ │
│ │ $connect → Lambda (auth, connection tracking) │ │
│ │ $disconnect → Lambda (cleanup) │ │
│ │ chat → Lambda (message handling) │ │
│ │ stream → Lambda (AI response streaming) │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ DynamoDB │
│ (Connection Store) │
└───────────────────────┘
Implementation Tasks:
1. Create API Gateway WebSocket API
2. Create Lambda functions for connection management
3. Create DynamoDB table for connection tracking
4. Update Laravel to push to API Gateway (via SDK)
5. Update frontend JavaScript (replace pusher-js with native WebSocket)
6. Create broadcasting driver for API Gateway
Files to Update:
- config/broadcasting.php - Add apigateway driver
- resources/views/default/js/createEcho.js - WebSocket client
- Create app/Broadcasting/ApiGatewayBroadcaster.php
2.3 Sentry → CloudWatch + X-Ray¶
Current Usage:
- Error tracking and alerting
- Performance monitoring
- Files: config/sentry.php, app/Http/Middleware/SentryContextMiddleware.php
Migration Path:
| Sentry Feature | AWS Equivalent |
|---|---|
| Error capture | CloudWatch Logs + Alarms |
| Performance traces | X-Ray |
| Release tracking | CodeDeploy + CloudWatch |
| User context | X-Ray annotations |
Implementation Tasks:
1. Configure CloudWatch Logs agent on EC2
2. Enable X-Ray daemon on EC2 instances
3. Add X-Ray SDK to Laravel (aws/aws-xray-sdk)
4. Create CloudWatch alarms for error patterns
5. Remove Sentry package and middleware
Files to Update:
- composer.json - Remove sentry/sentry-laravel, add aws/aws-xray-sdk
- app/Exceptions/Handler.php - Remove Sentry, add CloudWatch
- app/Http/Kernel.php - Remove Sentry middleware
- Delete config/sentry.php
- Delete app/Http/Middleware/SentryContextMiddleware.php
2.4 Direct AI APIs → Bedrock Only¶
Current Direct APIs: - OpenAI (GPT-4, DALL-E) - Anthropic direct (Claude) - Gemini - DeepSeek - Perplexity (keep - data enrichment)
Already on Bedrock: - Claude (all models via Bedrock) - Stable Diffusion (image generation)
Migration Tasks:
1. Set AI_DEFAULT_ENGINE=bedrock in production
2. Disable non-Bedrock engine selection in UI
3. Update entity driver mapping to route all AI through Bedrock
4. Keep capability parity (ensure Bedrock Claude covers all use cases)
Note: This is partially complete per existing compliance plan.
Part 3: HubSpot Integration Tightening¶
3.1 Current State¶
Minimal integration (app/Extensions/Hubspot/System/Services/HubspotService.php):
- getCrmContacts() - List contacts
- createCrmContacts() - Create contact
3.2 Recommended Enhancements¶
For co-sell workflow automation:
// Expanded HubSpot Service Capabilities
class HubspotService
{
// Existing
public function getCrmContacts(): array;
public function createCrmContacts(): array;
// NEW: Deal/Opportunity Management
public function createDeal(array $data): array;
public function updateDealStage(string $dealId, string $stage): array;
public function getDealsByPipeline(string $pipelineId): array;
// NEW: Company Management
public function createCompany(array $data): array;
public function associateContactToCompany(string $contactId, string $companyId): array;
// NEW: Custom Properties (for AWS Marketplace data)
public function setCustomProperties(string $objectType, string $objectId, array $properties): array;
// NEW: Webhooks (from HubSpot to Vell)
public function registerWebhook(string $eventType, string $url): array;
// NEW: Sync Operations
public function syncMarketplaceListing(MarketplaceListing $listing): array;
public function syncCoSellOpportunity(CoSellOpportunity $opportunity): array;
}
3.3 HubSpot ↔ Vell Data Flow¶
┌─────────────────────────────────────────────────────────────┐
│ VELL │
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ Marketplace │────▶│ HubSpot Sync Service │ │
│ │ Partner Data │ │ (New) │ │
│ └─────────────────┘ └──────────────┬──────────────┘ │
│ │ │
│ ┌─────────────────┐ │ │
│ │ Co-Sell │────────────────────┤ │
│ │ Opportunities │ │ │
│ └─────────────────┘ │ │
└─────────────────────────────────────────┼───────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ HUBSPOT │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Contacts │ │ Companies│ │ Deals │ │ Custom │ │
│ │ │ │(Partners)│ │(Co-Sell) │ │Properties│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ Custom Properties: │
│ • aws_marketplace_listing_id │
│ • aws_partner_id │
│ • cosell_opportunity_status │
│ • marketplace_seo_score │
│ • last_vell_sync_at │
└─────────────────────────────────────────────────────────────┘
3.4 HubSpot vs Kajabi Delineation¶
| Function | HubSpot | Kajabi |
|---|---|---|
| CRM/Contact management | ✅ Primary | ❌ |
| Deal/Pipeline tracking | ✅ Primary | ❌ |
| Marketing automation | ✅ Secondary | ✅ Primary |
| Landing pages | ❌ | ✅ Primary |
| Course/Content delivery | ❌ | ✅ Primary |
| Email campaigns | ✅ Available | ✅ Primary |
| Partner co-sell tracking | ✅ Primary | ❌ |
Recommendation: Use HubSpot for B2B partner/co-sell workflows; keep Kajabi for B2C marketing at app.vell.ai.
Part 4: Email Strategy (Post-Pinpoint)¶
4.1 Pinpoint Deprecation Impact¶
Per AWS announcement: - End of support: October 30, 2026 - No new customers: May 20, 2025 - Email recommendation: Migrate to Amazon SES
4.2 Recommended Email Architecture¶
┌─────────────────────────────────────────────────────────────┐
│ EMAIL STRATEGY │
├─────────────────────────────────────────────────────────────┤
│ │
│ TRANSACTIONAL (AWS SES) MARKETING (HubSpot) │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ • Password reset │ │ • Newsletters │ │
│ │ • Email verify │ │ • Drip campaigns │ │
│ │ • Order confirm │ │ • Partner nurture │ │
│ │ • System alerts │ │ • Co-sell updates │ │
│ │ • API notifications │ │ │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ config/mail.php HubSpot Marketing │
│ driver: ses (existing account) │
│ │
└─────────────────────────────────────────────────────────────┘
You likely already have this - Laravel typically uses SES for transactional. Verify in config/mail.php.
Part 5: Implementation Phases¶
Phase 1: API Versioning Foundation (Immediate)¶
Tasks:
1. Create routes/api_v1.php mirroring current routes/api.php
2. Create App\Http\Controllers\Api\V1\ namespace
3. Update RouteServiceProvider.php to load versioned routes
4. Add deprecation headers to unversioned endpoints
5. Update API documentation
Files:
- routes/api_v1.php (new)
- app/Providers/RouteServiceProvider.php (update)
- app/Http/Controllers/Api/V1/ (new directory)
Phase 2: Partner API Endpoints¶
Tasks: 1. Create partner authentication (API keys, OAuth2) 2. Implement partner-specific endpoints 3. Add rate limiting per partner 4. Create webhook infrastructure
Files:
- app/Http/Controllers/Api/V1/Partners/ (new)
- app/Models/PartnerApiKey.php (new)
- Database migration for partner API keys
Phase 3: AWS Migration - Sentry → CloudWatch¶
Tasks: 1. Install X-Ray SDK 2. Configure CloudWatch agent 3. Create error alarms 4. Remove Sentry dependencies 5. Test error capture
Effort: Low (1-2 days)
Phase 4: AWS Migration - Pusher → API Gateway WebSocket¶
Tasks: 1. Create API Gateway WebSocket API (CloudFormation/CDK) 2. Create Lambda handlers 3. Create DynamoDB connection table 4. Create Laravel broadcasting driver 5. Update frontend WebSocket client 6. Migration testing
Effort: Medium (3-5 days)
Phase 5: HubSpot Integration Enhancement¶
Tasks: 1. Expand HubspotService with deal/company methods 2. Create custom properties in HubSpot 3. Build sync service for marketplace data 4. Create webhook handlers 5. Test bi-directional sync
Effort: Medium (2-3 days)
Phase 6: Bedrock Consolidation¶
Tasks: 1. Audit remaining direct AI API usage 2. Ensure Bedrock parity for all use cases 3. Toggle engines to Bedrock-only in production 4. Update UI to hide non-Bedrock options
Effort: Low-Medium (already mostly done)
Part 6: Success Metrics¶
AWS Compliance¶
| Metric | Current | Target |
|---|---|---|
| AWS-deployed services | ~65% | 100% (of countable services) |
| External AI APIs | Multiple | Bedrock only |
| Real-time infrastructure | Pusher | API Gateway WebSocket |
| Error tracking | Sentry | CloudWatch + X-Ray |
API Readiness¶
| Metric | Current | Target |
|---|---|---|
| API versioning | None | v1 stable |
| Partner endpoints | 0 | Full CRUD |
| API documentation | Basic | OpenAPI 3.0 |
| Rate limiting | Global | Per-partner |
HubSpot Integration¶
| Metric | Current | Target |
|---|---|---|
| Synced objects | Contacts only | Contacts, Companies, Deals |
| Custom properties | 0 | 5+ marketplace fields |
| Automation triggers | 0 | Co-sell stage changes |
Appendix A: Files Reference¶
API Versioning¶
routes/api.php # Current (to deprecate)
routes/api_v1.php # New versioned routes
app/Providers/RouteServiceProvider.php # Route loading
app/Http/Controllers/Api/V1/ # Versioned controllers
AWS Migration¶
config/broadcasting.php # Pusher → API Gateway
config/sentry.php # To remove
app/Http/Middleware/SentryContextMiddleware.php # To remove
app/Exceptions/Handler.php # Update for CloudWatch
HubSpot¶
app/Extensions/Hubspot/System/Services/HubspotService.php # Expand
app/Extensions/Hubspot/extension.json # Version bump
Appendix B: External Services Classification¶
Counted Against 100% AWS (Must Migrate)¶
- ~~Pusher~~ → API Gateway WebSocket
- ~~Sentry~~ → CloudWatch + X-Ray
- ~~Direct OpenAI/Anthropic/Gemini~~ → Bedrock only
Not Counted (External by Necessity)¶
- Payment: Stripe, PayPal, Razorpay, etc.
- OAuth: Google, Facebook, Apple, GitHub
- CRM: HubSpot (business tool)
- Marketing: Kajabi (front-end)
- Search: Serper (data enrichment)
- Social: Twitter, LinkedIn, Instagram APIs
Document Version: 1.0 Last Updated: 2025-12-13