learning_ai_common_plat/AI.dev/SKILLS/local-development.md

Local Development Setup Skill

Description: Start and manage all backend services locally for development and testing.

When to Use

• Setting up a new development machine
• Starting work on a feature that spans multiple services
• Running integration tests locally
• Demonstrating the full system

Prerequisites

• All repos cloned to $HOME/code/mygh/
• Python 3.12+ with virtual environment
• Node.js 20+
• pnpm installed globally
• .env files configured with necessary secrets

Quick Start

cd $HOME/code/mygh/learning_voice_ai_agent

# Start all 8 services at once
./run-local-all-services.sh start

# Verify all services are running
./run-local-all-services.sh status

Service URLs and Details

Service	URL	Log File	Process	Port
Backend API (FastAPI)	http://localhost:8000	.logs/backend.log	Python	8000
Growth Service (Fastify)	http://localhost:4001	.logs/growth-service.log	Node.js	4001
Billing Service (Fastify)	http://localhost:4002	.logs/billing-service.log	Node.js	4002
Platform Service (Fastify)	http://localhost:4003	.logs/platform-service.log	Node.js	4003
Admin Dashboard	http://localhost:3001	.logs/admin-dashboard.log	Next.js	3001
User Dashboard	http://localhost:3002	.logs/user-dashboard.log	Next.js	3002
Tracker Service (Fastify)	http://localhost:4004	.logs/tracker-service.log	Node.js	4004
Tracker Dashboard	http://localhost:3003	.logs/tracker-dashboard.log	Next.js	3003

Health Check Commands

# Quick health check for all services
curl -s http://127.0.0.1:8000/health && echo " ✓ Backend"
curl -s http://127.0.0.1:4001/health && echo " ✓ Growth"
curl -s http://127.0.0.1:4002/health && echo " ✓ Billing"
curl -s http://127.0.0.1:4003/health && echo " ✓ Platform"
curl -s http://127.0.0.1:4004/health && echo " ✓ Tracker"

# Check dashboards (HTTP status codes)
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3001 && echo " ✓ Admin Dashboard"
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3002 && echo " ✓ User Dashboard"
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3003 && echo " ✓ Tracker Dashboard"

Manual Service Startup

If the script doesn't work, start services manually:

1. Common Platform Services

cd $HOME/code/mygh/learning_ai_common_plat

# Growth Service
cd services/growth-service
pnpm install
pnpm dev > $HOME/code/mygh/learning_voice_ai_agent/.logs/growth-service.log 2>&1 &

# Billing Service
cd ../billing-service
pnpm install
pnpm dev > $HOME/code/mygh/learning_voice_ai_agent/.logs/billing-service.log 2>&1 &

# Platform Service
cd ../platform-service
pnpm install
pnpm dev > $HOME/code/mygh/learning_voice_ai_agent/.logs/platform-service.log 2>&1 &

# Tracker Service
cd ../tracker-service
pnpm install
pnpm dev > $HOME/code/mygh/learning_voice_ai_agent/.logs/tracker-service.log 2>&1 &

2. Voice Agent Services

cd $HOME/code/mygh/learning_voice_ai_agent

# Backend API
cd backend
source ../.venv/bin/activate
python -m uvicorn src.main:app --reload --host 0.0.0.0 --port 8000 > ../.logs/backend.log 2>&1 &

# Admin Dashboard
cd ../admin-dashboard-web
npm install
npm run dev > ../.logs/admin-dashboard.log 2>&1 &

# User Dashboard
cd ../user-dashboard-web
npm install
npm run dev > ../.logs/user-dashboard.log 2>&1 &

# Tracker Dashboard
cd ../tracker-dashboard-web
npm install
npm run dev > ../.logs/tracker-dashboard.log 2>&1 &

Environment Setup

Required Environment Files

1. Root .env (learning_voice_ai_agent)

   COSMOS_ENDPOINT=https://...
   COSMOS_KEY=...
   COSMOS_DATABASE=lysnrai
   JWT_SECRET=...
   AZURE_SPEECH_KEY=...
   AZURE_SPEECH_REGION=eastus
   AZURE_OPENAI_ENDPOINT=...
   AZURE_OPENAI_KEY=...
   AZURE_OPENAI_DEPLOYMENT=gpt-4o-mini
   

2. Dashboard .env.local files

   # admin-dashboard-web/.env.local
   COSMOS_ENDPOINT=https://...
   COSMOS_KEY=...
   JWT_SECRET=...
   NEXT_PUBLIC_APP_URL=http://localhost:3001
   
   # user-dashboard-web/.env.local
   COSMOS_ENDPOINT=https://...
   COSMOS_KEY=...
   JWT_SECRET=...
   NEXT_PUBLIC_APP_URL=http://localhost:3002
   
   # tracker-dashboard-web/.env.local
   TRACKER_API_URL=http://localhost:4004
   PLATFORM_API_URL=http://localhost:4003
   JWT_SECRET=...
   

Log Management

# View all logs in real-time
tail -f .logs/*.log

# View specific service log
tail -f .logs/backend.log

# Search logs for errors
grep -i "error\|exception\|failed" .logs/*.log

# Clear all logs
> .logs/backend.log .logs/growth-service.log .logs/billing-service.log \
  .logs/platform-service.log .logs/tracker-service.log \
  .logs/admin-dashboard.log .logs/user-dashboard.log .logs/tracker-dashboard.log

Stop Services

# Stop all services at once
./run-local-all-services.sh stop

# Or manually kill processes
pkill -f "uvicorn src.main:app"
pkill -f "next dev"
pkill -f "tsx.*src/server.ts"

Common Issues

Port Already in Use

# Find process using port
lsof -i :8000

# Kill it
kill -9 <PID>

# Or use this script to kill all dev ports
./run-local-all-services.sh stop

Service Won't Start

1. Check the log file: tail .logs/<service>.log
2. Verify environment variables are set
3. Ensure dependencies are installed
4. Check if required ports are available

Dashboard Can't Connect to Services

1. Verify services are running: ./run-local-all-services.sh status
2. Check CORS configuration in services
3. Verify API URLs in dashboard .env.local files

Development Tips

• Use the script - ./run-local-all-services.sh handles process management and logging
• Check logs first - Most issues have clear error messages in the logs
• Restart individual services - No need to restart everything unless there's a dependency issue
• Hot reload - All services support hot reload for fast development
• Use health endpoints - Quick way to verify services are responding

Related Skills

• Debug Service - When something goes wrong
• Production Readiness - Before releasing
• Docker Compose - Alternative containerized setup