Skip to content

COMPLETE_GUIDE.md

Latest commit

 

History

History
736 lines (555 loc) · 18.2 KB

COMPLETE_GUIDE.md

File metadata and controls

736 lines (555 loc) · 18.2 KB
Raw

VectorOS - Complete Guide

Everything you need to know about VectorOS in one place.

Last Updated: November 5, 2025 Status: 🟢 Production Ready Version: 1.0 - Autonomous Intelligence

📋 Table of Contents

  1. What is VectorOS
  2. Current Status
  3. Architecture
  4. Deployment
  5. Production Checklist
  6. Roadmap
  7. Cost & Pricing
  8. Troubleshooting

What is VectorOS

VectorOS is an AI-powered Revenue Intelligence Platform - not a CRM.

The Difference:

CRM with AI:

  • User clicks "Generate Insights"
  • AI analyzes on-demand
  • Manual, reactive

VectorOS (Revenue Intelligence):

  • AI monitors ALL deals every 30 minutes automatically
  • Detects anomalies proactively (stale deals, velocity drops, risk signals)
  • Generates insights without user action
  • Never misses a signal, even over weekends

Target Market:

  • B2B SaaS companies
  • $5M-$50M ARR
  • 10-50 sales reps
  • 100-5,000 active deals

Pricing Strategy:

  • Starter: $500/month (up to 500 deals, 5 users)
  • Growth: $1,500/month (up to 2,000 deals, 20 users)
  • Enterprise: $3,000/month (unlimited)

Current Status

✅ Phase 1: Core Platform (100% Complete)

Feature Status
User Authentication (Clerk) ✅
Workspace Management ✅
Deal CRUD Operations ✅
Dashboard Metrics ✅
Health Scoring (6 dimensions) ✅
Activity Tracking ✅
Database Schema ✅

✅ Phase 2: AI Intelligence (100% Complete)

Feature Status
Claude Sonnet 4.5 Integration ✅
RAG-based Insights ✅
Deal Analysis ✅
Batch Processing ✅
Confidence Scoring ✅
Actionable Recommendations ✅

✅ Phase 3: Autonomous Monitoring (100% Complete)

Feature Status
Continuous Worker (30-min cron) ✅
5 Anomaly Detection Patterns ✅
Proactive Insight Generation ✅
Batch Insights API ✅
Deal-First UI (scalable) ✅
Production Deployment Configs ✅

Test Results (Verified Nov 5, 2025):

✅ Workspaces: 1
✅ Deals Analyzed: 1
✅ Insights Generated: 2
✅ Critical Alerts: 1
✅ Duration: 19.42s
✅ Status: Success

Architecture

System Overview

┌─────────────────────────────────────────────────────────┐
│                    FRONTEND (Next.js)                    │
│                      Port: 3000                          │
│  • Dashboard, Deals, Insights pages                     │
│  • Clerk authentication                                 │
│  • Deal-first insights UI                               │
└──────────────────────┬──────────────────────────────────┘
                       │ REST API
                       ▼
┌─────────────────────────────────────────────────────────┐
│                  BACKEND (Express + Prisma)             │
│                      Port: 3001                          │
│  • Deal, Insight, User services                         │
│  • Batch insights endpoint                              │
│  • Neon PostgreSQL connection                           │
└──────────────────────┬──────────────────────────────────┘
                       │ REST API
                       ▼
┌─────────────────────────────────────────────────────────┐
│              AI CORE (FastAPI + Claude)                 │
│                      Port: 8000                          │
│  • Insight generation                                   │
│  • Deal scoring                                         │
│  • Claude Sonnet 4.5 integration                        │
└─────────────────────────────────────────────────────────┘

          ┌────────────────────────────────────┐
          │   AUTONOMOUS WORKER (Python)       │
          │   Runs every 30 minutes            │
          │   • Fetches all deals              │
          │   • Detects anomalies              │
          │   • Generates insights             │
          │   • Saves to database              │
          └────────────────────────────────────┘

5 Anomaly Detection Patterns

  1. Stale Deal - No activity >7 days (critical if >14 days)
  2. Stuck in Stage - Exceeds stage duration threshold
  3. Low Probability - Below minimum for current stage
  4. High Value at Risk - >$10K with risk signals
  5. Close Date Pressure - Approaching close with low probability

Data Flow: Autonomous Monitoring

[Every 30 min: Cron trigger]
         ↓
[Worker: continuous_monitor.py]
         ↓
[Fetch all active deals from Backend API]
         ↓
[Analyze each deal locally for anomalies]
         ↓
[For deals with anomalies:]
    ↓
    [Build enhanced prompt with context]
    ↓
    [Call Claude Sonnet 4.5]
    ↓
    [Parse JSON response → insights]
    ↓
    [POST to /api/v1/workspaces/:id/insights/batch]
    ↓
    [Backend saves to database]
         ↓
[Frontend displays automatically]

Database Schema

User (Clerk auth)
 ↓ (1:N)
Workspace (multi-tenant)
 ↓ (1:N)
Deal (title, value, stage, probability)
 ↓ (1:N)
Insight (type, priority, confidence, actions)
 ↓ (1:N)
Activity (emails, calls, meetings)

Key Relations:

  • Insight has dealId, userId, workspaceId (proper foreign keys)
  • Indexes on workspaceId, dealId, userId for performance

Deployment

Prerequisites

  1. Neon PostgreSQL - Get free database at https://console.neon.tech
  2. Anthropic API Key - Get at https://console.anthropic.com
  3. Clerk Account - Get at https://dashboard.clerk.com

Environment Variables

Create .env in project root:

# Database (Neon PostgreSQL)
DATABASE_URL="postgresql://user:pass@host.neon.tech/db?sslmode=require"

# AI (Anthropic Claude)
ANTHROPIC_API_KEY="sk-ant-api03-..."

# Auth (Clerk)
CLERK_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."

# API URLs (update for production)
NEXT_PUBLIC_API_URL="http://localhost:3001"
AI_CORE_URL="http://localhost:8000"

Option 1: Railway (Recommended - 5 minutes)

Why Railway?

  • Built-in cron jobs for worker
  • Automatic SSL certificates
  • Simple environment variable management
  • $20-50/month all-in

Steps:

# 1. Install CLI
npm i -g @railway/cli

# 2. Login
railway login

# 3. Initialize project
cd /Users/pedrooliveiratengelmann/Desktop/VectorOS
railway init

# 4. Add environment variables in Railway dashboard
# Go to: railway.app → Your Project → Variables
# Add: DATABASE_URL, ANTHROPIC_API_KEY, CLERK_SECRET_KEY, etc.

# 5. Deploy
railway up

# 6. Check logs
railway logs ai-core-worker -f

Railway will automatically:

  • Deploy all 4 services (frontend, backend, AI core, worker)
  • Run worker every 30 minutes
  • Provide public URLs
  • Set up health checks

Option 2: Vercel (Frontend) + Render (Backend/AI/Worker)

Why this combo?

  • Vercel = Best Next.js hosting (free tier available)
  • Render = Simple backend hosting with cron jobs
  • Cost: $0-20 (Vercel) + $28 (Render) = $28-48/month

Steps:

Vercel (Frontend):

npm i -g vercel
cd frontend
vercel --prod

Render (Backend, AI Core, Worker):

  1. Go to https://render.com
  2. Connect GitHub repository
  3. Create 3 Web Services:
    • Backend: Build: npm install && npx prisma generate, Start: npm start
    • AI Core: Build: pip install -r requirements.txt, Start: uvicorn src.main:app --host 0.0.0.0 --port $PORT
  4. Create 1 Cron Job:
    • Worker: Schedule: */30 * * * *, Command: python -m src.workers.continuous_monitor

Option 3: Docker Compose (Self-Hosted)

Why Docker?

  • Full control
  • Run anywhere (VPS, DigitalOcean, AWS, home server)
  • Cost: Infrastructure only (~$10-20/month for VPS)

Steps:

# 1. Clone repository
git clone https://github.com/ptengelmann/VectorOS.git
cd VectorOS

# 2. Create .env file
cp .env.example .env
# Edit .env with your values

# 3. Start all services
docker-compose up -d

# 4. Check logs
docker-compose logs -f worker

# 5. Access application
# Frontend: http://localhost:3000
# Backend: http://localhost:3001
# AI Core: http://localhost:8000

Post-Deployment Verification

1. Check Health Endpoints:

curl https://your-backend.railway.app/health
curl https://your-ai-core.railway.app/health

Expected: {"status": "ok"} or {"status": "healthy"}

2. Check Worker Logs:

Railway:

railway logs ai-core-worker -f

Render:

  • Dashboard → Cron Jobs → Logs

Docker:

docker-compose logs -f worker

Expected output every 30 minutes:

🤖 STARTING CONTINUOUS MONITORING CYCLE
📊 Found X active workspaces
📋 Found X active deals
✅ MONITORING CYCLE COMPLETE
   Deals Analyzed: X
   Insights Generated: X
   Critical Alerts: X

3. Test End-to-End:

  1. Sign in to your deployed app
  2. Create a test deal (set probability to 10%, value $10,000)
  3. Wait 30 minutes
  4. Check Insights page - should see automatic insights

Production Checklist

🚨 Critical (Must Have Before Launch)

  • Sentry Error Tracking

    • Catch worker failures
    • Monitor Claude API errors
    • Alert on critical issues

  • Environment Variables Verified

    • Production DATABASE_URL (not dev)
    • Production Clerk keys (not test keys)
    • ANTHROPIC_API_KEY has sufficient credits

  • CORS Configuration

    • Backend allows only your frontend domain
    • No Access-Control-Allow-Origin: * in production

  • Rate Limiting

    • Backend API has rate limits (prevent abuse)
    • Claude API rate limits respected

  • Health Monitoring

    • Uptime Robot monitoring /health endpoints
    • Alerts to email/Slack if services go down

⚠️ Important (Should Have)

  • Database Backups

    • Verify Neon automatic backups enabled
    • Test restore process once

  • Logging Infrastructure

    • Aggregate logs (Better Stack, Logtail)
    • Track worker success/failure rate
    • Monitor Claude API costs

  • Load Testing

    • Test with 100+ deals
    • Verify worker completes in <60 seconds
    • Check database query performance

  • SSL Certificates

    • HTTPS enabled (automatic with Railway/Vercel)
    • Verify certificate validity

💡 Nice to Have

  • CI/CD Pipeline

    • GitHub Actions for auto-deploy
    • Run tests before deploy

  • API Documentation

    • Swagger/OpenAPI docs
    • Internal API reference

  • Analytics

    • Track user behavior (PostHog, Mixpanel)
    • Measure insight view rate, action rate

Roadmap

✅ Completed (Nov 2025)

  • Core platform with authentication
  • AI insights with Claude Sonnet 4.5
  • Autonomous monitoring worker
  • Deal-first scalable UI
  • Production deployment configs

📅 Week 1: Notifications (Next)

Goal: Get insights in front of users immediately

  • Email notifications for critical insights (SendGrid)
  • Daily digest emails (summary of all insights)
  • Slack integration (post critical alerts to channel)
  • SMS alerts for high-value deals at risk (>$50K) - Twilio
  • Notification preferences UI

Estimated Effort: 3-4 days Value: Increases insight visibility and action rate

📅 Week 2: Email & Calendar Integration

Goal: Automatic data capture (zero manual input)

  • Gmail OAuth integration
  • Email ingestion service (capture deal-related emails)
  • Entity extraction (detect companies, contacts, sentiment)
  • Activity auto-logging (emails → activity timeline)
  • Google Calendar integration
  • Meeting frequency tracking
  • Ghosting detection (no response in 7+ days)

Estimated Effort: 5-6 days Value: Eliminates manual data entry, improves accuracy

Files to create:

ai-core/src/services/
  ├── email_ingestion.py
  ├── entity_extractor.py
  └── calendar_sync.py

backend/src/services/
  └── gmail_oauth.service.ts

📅 Week 3: Machine Learning Models

Goal: Predictive accuracy beyond heuristics

  • Historical data collection (win/loss outcomes)
  • Feature engineering (deal attributes → model inputs)
  • Train win probability model (XGBoost or Random Forest)
  • Predict close dates with confidence intervals
  • A/B test ML model vs current algorithm
  • Outcome learning system (improve model with new data)

Estimated Effort: 7-8 days Value: Higher accuracy, better forecasting

Files to create:

ai-core/src/ml/
  ├── win_probability_model.py
  ├── close_date_predictor.py
  ├── feature_engineering.py
  └── outcome_tracker.py

📅 Week 4: Revenue Forecasting

Goal: Predictable revenue with confidence intervals

  • Monte Carlo simulation (probabilistic forecasting)
  • Daily forecast updates
  • Pipeline gap analysis (what's needed to hit target)
  • Scenario planning ("What if we close these 5 deals?")
  • Forecast drift detection (track accuracy over time)
  • Revenue forecasting dashboard

Estimated Effort: 6-7 days Value: Replaces spreadsheet forecasting

Cost & Pricing

Monthly Operating Costs

Infrastructure (1,000 deals):

Service Cost
Railway (All services) $20-50
Neon PostgreSQL $10-20
Claude API (Anthropic) $90
SendGrid (Email) $15
Sentry (Error tracking) $26
Total $161-201/month

Claude API Scaling:

  • 100 deals → ~50 insights/day → $23/month
  • 1,000 deals → ~200 insights/day → $90/month
  • 5,000 deals → ~500 insights/day → $225/month

Revenue Model

Pricing Tiers:

  • Starter: $500/month (500 deals, 5 users)
  • Growth: $1,500/month (2,000 deals, 20 users)
  • Enterprise: $3,000/month (unlimited)

Unit Economics (Growth tier):

  • Revenue: $1,500/month
  • Operating costs: $161/month
  • Gross margin: 89% ($1,339/month)
  • LTV (2-year avg): $36,000

Troubleshooting

Worker Not Running

Symptom: No insights appearing after 30 minutes

Check 1: Worker logs

# Railway
railway logs ai-core-worker

# Render
Dashboard → Cron Jobs → Logs

# Docker
docker-compose logs worker

Check 2: Verify cron schedule

  • Railway: Check railway.json → cron.schedule
  • Render: Verify schedule is */30 * * * *

Check 3: Environment variables

# Verify these are set:
echo $DATABASE_URL
echo $ANTHROPIC_API_KEY

Database Connection Errors

Symptom: Could not connect to database

Fix:

  • Verify DATABASE_URL includes ?sslmode=require for Neon
  • Check database is not paused (Neon free tier auto-pauses after inactivity)
  • Test connection:
psql $DATABASE_URL -c "SELECT 1;"

Claude API Errors

Symptom: Could not resolve authentication method

Fix:

  • Verify ANTHROPIC_API_KEY is set correctly
  • Check key format: Should start with sk-ant-api03-
  • Verify API key has credits: https://console.anthropic.com
  • Check rate limits not exceeded

Frontend Can't Connect to Backend

Symptom: Network errors in browser console

Fix:

  • Verify backend is running: curl https://your-backend.railway.app/health
  • Check NEXT_PUBLIC_API_URL environment variable
  • Verify CORS is configured in backend:
app.use(cors({
  origin: process.env.FRONTEND_URL || 'http://localhost:3000'
}));

Worker Generates 0 Insights

Symptom: Worker runs successfully but no insights created

Possible causes:

  1. No deals in database
  2. All deals are "won" or "lost" (worker only processes active deals)
  3. No anomalies detected (all deals are healthy - this is good!)

Debug:

# Run worker manually with verbose output
cd ai-core
source venv/bin/activate
python -m src.workers.continuous_monitor

Key Files Reference

Core Services

  • ai-core/src/workers/continuous_monitor.py - Autonomous monitoring engine (517 lines)
  • backend/src/index.ts - Backend API routes + batch insights endpoint
  • frontend/app/insights/page.tsx - Deal-first insights UI
  • backend/prisma/schema.prisma - Database schema with relations

Deployment

  • railway.json - Railway deployment config with cron
  • docker-compose.yml - Complete Docker setup
  • .env.example - Environment variable template
  • start-autonomous.sh - Local startup script
  • stop-autonomous.sh - Local shutdown script

Documentation

  • README.md - Quick start guide
  • COMPLETE_GUIDE.md - This file (everything in one place)
  • AUTONOMOUS_MONITORING.md - Deep dive on autonomous system

Quick Commands

Development

# Start all services locally
./start-autonomous.sh

# Stop all services
./stop-autonomous.sh

# Check logs
tail -f logs/worker.log
tail -f logs/backend.log
tail -f logs/ai-core.log

Deployment

# Railway
railway up

# Docker
docker-compose up -d

# Vercel (frontend only)
cd frontend && vercel --prod

Testing

# Run worker once
cd ai-core
source venv/bin/activate
python -m src.workers.continuous_monitor

# Test backend health
curl http://localhost:3001/health

# Test AI Core health
curl http://localhost:8000/health

Support

For issues:

  1. Check this guide's troubleshooting section
  2. Review worker logs
  3. Verify environment variables
  4. Test health endpoints

Last Updated: November 5, 2025 Status: 🟢 Production Ready Next Milestone: Deploy + Week 1 (Notifications)