job-forge/docs/development_setup.md

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

git clone https://github.com/your-org/jobforge-mvp.git
cd jobforge-mvp

2. Environment Configuration

# Copy environment template
cp .env.example .env

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

Required Environment Variables:

# 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

# 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

# .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

# 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

# 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

# Stop all services
docker-compose down

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

Rebuild Services

# 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

# 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

# WARNING: This deletes all data
docker-compose down -v
docker-compose up -d postgres

Database Migrations (Future)

# When Alembic is added
docker-compose exec backend alembic upgrade head

Database Schema Verification

After startup, verify tables exist:

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

curl http://localhost:8000/health
# Expected: {"status": "healthy", "service": "jobforge-backend"}

2. Database Connection

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"

# 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"

# 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"

# 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"

# 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"

# 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

# 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

# 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.