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

```bash
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 |
| 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 Dashboard          | http://localhost:3003 | `.logs/tracker-dashboard.log` | Next.js | 3003 |

## Health Check Commands

```bash
# Quick health check for all services
curl -s http://127.0.0.1:8000/health && echo " ✓ Backend"
curl -s http://127.0.0.1:4003/health && echo " ✓ Platform"

# 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

```bash
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

```bash
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)

   ```bash
   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

   ```bash
   # 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

```bash
# 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

```bash
# 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

```bash
# 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](./debug-service.md) - When something goes wrong
- [Production Readiness](./production-readiness.md) - Before releasing
- [Docker Compose](./docker-compose.md) - Alternative containerized setup