# JobForge MVP - Development Setup Guide

**Version:** 1.0.0 MVP  
**Target Audience:** Developers  
**Last Updated:** July 2025

---

## 🎯 Prerequisites

### Required Software
- **Docker Desktop** 4.20+ with Docker Compose
- **Git** 2.30+
- **Text Editor** (VS Code recommended)
- **API Keys** (Claude, OpenAI)

### System Requirements
- **RAM:** 8GB minimum (Docker containers + database)
- **Storage:** 10GB free space
- **OS:** Windows 10+, macOS 12+, or Linux

---

## 🚀 Quick Start (5 Minutes)

### 1. Clone Repository
```bash
git clone https://github.com/your-org/jobforge-mvp.git
cd jobforge-mvp
```

### 2. Environment Configuration
```bash
# Copy environment template
cp .env.example .env

# Edit .env file with your API keys
nano .env  # or use your preferred editor
```

**Required Environment Variables:**
```bash
# API Keys (REQUIRED)
CLAUDE_API_KEY=your_claude_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

# Database (Auto-configured for local development)
DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp

# JWT Secret (Generate random string)
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production

# Development Settings
DEBUG=true
LOG_LEVEL=INFO
```

### 3. Start Development Environment
```bash
# Start all services (PostgreSQL, Backend, Frontend)
docker-compose up -d

# View logs to ensure everything started correctly
docker-compose logs -f
```

### 4. Verify Installation
- **Frontend:** http://localhost:8501
- **Backend API:** http://localhost:8000
- **API Documentation:** http://localhost:8000/docs
- **Database:** localhost:5432

---

## 🔧 Detailed Setup Instructions

### Getting API Keys

#### Claude API Key
1. Visit https://console.anthropic.com/
2. Create account or log in
3. Go to "API Keys" section
4. Create new key with name "JobForge Development"
5. Copy key to `.env` file

#### OpenAI API Key
1. Visit https://platform.openai.com/api-keys
2. Create account or log in  
3. Click "Create new secret key"
4. Name it "JobForge Development"
5. Copy key to `.env` file

### Environment File Setup
```bash
# .env file (copy from .env.example)

# =============================================================================
# API KEYS - REQUIRED FOR DEVELOPMENT
# =============================================================================
CLAUDE_API_KEY=sk-ant-api03-xxx...
OPENAI_API_KEY=sk-xxx...

# =============================================================================
# DATABASE CONFIGURATION
# =============================================================================
DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
POSTGRES_DB=jobforge_mvp
POSTGRES_USER=jobforge_user
POSTGRES_PASSWORD=jobforge_password

# =============================================================================
# AUTHENTICATION
# =============================================================================
JWT_SECRET_KEY=super-secret-jwt-key-minimum-32-characters-long
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=24

# =============================================================================
# APPLICATION SETTINGS
# =============================================================================
DEBUG=true
LOG_LEVEL=INFO
BACKEND_URL=http://backend:8000

# =============================================================================
# AI PROCESSING SETTINGS
# =============================================================================
CLAUDE_MODEL=claude-sonnet-4-20250514
OPENAI_EMBEDDING_MODEL=text-embedding-3-large
MAX_PROCESSING_TIME_SECONDS=120
```

---

## 🐳 Docker Setup

### Docker Compose Configuration
The `docker-compose.yml` file configures three main services:

#### PostgreSQL Database
- **Port:** 5432
- **Database:** jobforge_mvp
- **Extensions:** pgvector for AI embeddings
- **Data:** Persisted in Docker volume

#### Backend API (FastAPI)
- **Port:** 8000
- **Auto-reload:** Enabled for development
- **API Docs:** http://localhost:8000/docs

#### Frontend App (Dash)
- **Port:** 8501
- **Auto-reload:** Enabled for development

### Docker Commands

#### Start Services
```bash
# Start all services in background
docker-compose up -d

# Start with logs visible
docker-compose up

# Start specific service
docker-compose up backend
```

#### View Logs
```bash
# All services logs
docker-compose logs -f

# Specific service logs
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f postgres
```

#### Stop Services
```bash
# Stop all services
docker-compose down

# Stop and remove volumes (WARNING: Deletes database data)
docker-compose down -v
```

#### Rebuild Services
```bash
# Rebuild after code changes
docker-compose build

# Rebuild specific service
docker-compose build backend

# Rebuild and restart
docker-compose up --build
```

---

## 🗄️ Database Setup

### Automatic Database Initialization
The database is automatically set up when you first run `docker-compose up`:

1. **PostgreSQL starts** with pgvector extension
2. **Database created** with name `jobforge_mvp`
3. **Tables created** from `database/init.sql`
4. **Row Level Security** policies applied
5. **Sample data** inserted (optional)

### Manual Database Operations

#### Connect to Database
```bash
# Connect via Docker
docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp

# Connect from host (if PostgreSQL client installed)
psql -h localhost -p 5432 -U jobforge_user -d jobforge_mvp
```

#### Reset Database
```bash
# WARNING: This deletes all data
docker-compose down -v
docker-compose up -d postgres
```

#### Database Migrations (Future)
```bash
# When Alembic is added
docker-compose exec backend alembic upgrade head
```

### Database Schema Verification
After startup, verify tables exist:
```sql
-- Connect to database and run:
\dt

-- Expected tables:
-- users
-- applications  
-- documents
-- user_resumes
-- document_embeddings
```

---

## 🔍 Development Workflow

### Code Organization
```
src/
├── backend/           # FastAPI backend code
│   ├── main.py       # FastAPI app entry point
│   ├── api/          # API route handlers
│   ├── services/     # Business logic
│   ├── database/     # Database models and connection
│   └── models/       # Pydantic request/response models
├── frontend/         # Dash frontend code
│   ├── main.py       # Dash app entry point
│   ├── components/   # Reusable UI components
│   ├── pages/        # Page components
│   └── api_client/   # Backend API client
├── agents/           # AI processing agents
└── helpers/          # Shared utilities
```

### Making Code Changes

#### Backend Changes
1. **Modify code** in `src/backend/`
2. **FastAPI auto-reloads** automatically
3. **Test changes** at http://localhost:8000/docs

#### Frontend Changes  
1. **Modify code** in `src/frontend/`
2. **Dash auto-reloads** automatically  
3. **Test changes** at http://localhost:8501

#### Database Changes
1. **Modify** `database/init.sql`
2. **Reset database:** `docker-compose down -v && docker-compose up -d`

### Testing Your Setup

#### 1. Backend Health Check
```bash
curl http://localhost:8000/health
# Expected: {"status": "healthy", "service": "jobforge-backend"}
```

#### 2. Database Connection
```bash
curl http://localhost:8000/api/v1/auth/me
# Expected: {"detail": "Not authenticated"} (this is correct - no token)
```

#### 3. Frontend Access
Visit http://localhost:8501 - should see login page

#### 4. API Documentation
Visit http://localhost:8000/docs - should see Swagger UI

---

## 🐛 Troubleshooting

### Common Issues

#### "Port already in use"
```bash
# Check what's using the port
lsof -i :8501  # or :8000, :5432

# Kill the process or change ports in docker-compose.yml
```

#### "API Key Invalid"
```bash
# Verify API key format
echo $CLAUDE_API_KEY  # Should start with "sk-ant-api03-"
echo $OPENAI_API_KEY  # Should start with "sk-"

# Test API key manually
curl -H "Authorization: Bearer $CLAUDE_API_KEY" https://api.anthropic.com/v1/messages
```

#### "Database Connection Failed"
```bash
# Check if PostgreSQL is running
docker-compose ps postgres

# Check database logs
docker-compose logs postgres

# Try connecting manually
docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
```

#### "Frontend Won't Load"
```bash
# Check frontend logs
docker-compose logs frontend

# Common issue: Backend not ready
curl http://localhost:8000/health

# Restart frontend
docker-compose restart frontend
```

#### "AI Processing Fails"
```bash
# Check backend logs for API errors
docker-compose logs backend | grep -i error

# Verify API keys are loaded
docker-compose exec backend env | grep API_KEY
```

### Development Tips

#### Hot Reloading
- Both backend and frontend support hot reloading
- Database schema changes require full restart
- Environment variable changes require restart

#### Debugging
```bash
# Backend debugging with detailed logs
DEBUG=true LOG_LEVEL=DEBUG docker-compose up backend

# Frontend debugging
docker-compose exec frontend python src/frontend/main.py --debug
```

#### Performance Monitoring
```bash
# View container resource usage
docker stats

# View database performance
docker-compose exec postgres pg_stat_activity
```

---

## 📊 Development Tools

### Recommended VS Code Extensions
- **Python** (Microsoft)
- **Docker** (Microsoft)  
- **PostgreSQL** (Chris Kolkman)
- **REST Client** (Huachao Mao)
- **GitLens** (GitKraken)

### API Testing Tools
- **Built-in Swagger UI:** http://localhost:8000/docs
- **curl commands** (see API specification)
- **Postman** (import OpenAPI spec from `/openapi.json`)

### Database Tools
- **pgAdmin** (web-based PostgreSQL admin)
- **DBeaver** (database IDE)
- **psql** (command line client)

---

## 🚀 Next Steps

Once your environment is running:

1. **Create test account** at http://localhost:8501
2. **Review API documentation** at http://localhost:8000/docs
3. **Follow Database Design** document for schema details
4. **Check Testing Strategy** document for testing approach
5. **Start development** following the 8-week roadmap

---

## 📞 Getting Help

### Development Issues
- Check this troubleshooting section first
- Review Docker logs: `docker-compose logs`
- Verify environment variables: `docker-compose exec backend env`

### API Issues  
- Use Swagger UI for interactive testing
- Check API specification document
- Verify authentication headers

### Database Issues
- Connect directly: `docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp`
- Check database logs: `docker-compose logs postgres`
- Review database design document

---

*This setup guide should get you from zero to a working development environment in under 10 minutes. If you encounter issues not covered here, please update this document for future developers.*