job-forge/README.md

⚡ JobForge MVP

AI-Powered Job Application Management System

Transform your job search with intelligent document generation and strategic application management. JobForge uses Claude Sonnet 4 and OpenAI to create tailored resumes and cover letters through a 3-phase AI workflow.

---

🚀 Quick Start (5 Minutes)

Prerequisites

• Docker Desktop 4.20+ with Docker Compose
• API Keys: Claude API key, OpenAI API key
• Git 2.30+

1. Clone & Setup

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

# Copy environment template and add your API keys
cp .env.example .env
nano .env  # Add CLAUDE_API_KEY and OPENAI_API_KEY

2. Start Development Environment

# Start all services (PostgreSQL, Backend, Frontend)
docker-compose up -d

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

3. Verify Installation

Open these URLs to verify everything is working:

• Frontend Application: http://localhost:8501
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

4. Quick Validation

# Check backend health
curl http://localhost:8000/health

# Check all services are running
docker-compose ps

All services should show "Up" status. If any issues, see Troubleshooting below.

---

✨ What is JobForge?

JobForge is an AI-powered job application management system that streamlines your job search through intelligent document generation. Built for individual job seekers, it combines strategic application management with advanced AI to maximize your chances of landing interviews.

Key Features

• 3-Phase AI Workflow: Research → Resume Optimization → Cover Letter Generation
• Modern Interface: Professional web app with intuitive navigation
• Secure & Private: Complete user data isolation with PostgreSQL Row-Level Security
• AI-Powered: Claude Sonnet 4 for document generation, OpenAI for semantic matching

Technology Stack

• Frontend: Dash + Mantine components
• Backend: FastAPI + AsyncIO
• Database: PostgreSQL 16 + pgvector
• AI: Claude Sonnet 4, OpenAI embeddings
• Development: Docker Compose

---

🛠️ Development Commands

Essential Commands

# Start all services
docker-compose up -d

# View logs for all services
docker-compose logs -f

# View logs for specific service
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f postgres

# Stop all services
docker-compose down

# Rebuild after code changes
docker-compose up --build

# Reset database (WARNING: Deletes all data)
docker-compose down -v && docker-compose up -d

Testing

# Run backend tests
docker-compose exec backend pytest

# Run tests with coverage
docker-compose exec backend pytest --cov=src --cov-report=html

# Run specific test file
docker-compose exec backend pytest tests/unit/services/test_auth_service.py

Database Operations

# Connect to PostgreSQL database
docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp

# Check database health
curl http://localhost:8000/health

---

🏗️ Project Structure

jobforge-mvp/
├── src/
│   ├── backend/          # FastAPI backend code
│   │   ├── main.py      # FastAPI app entry point
│   │   ├── api/         # API route handlers
│   │   ├── services/    # Business logic
│   │   └── database/    # Database models and connection
│   ├── frontend/        # Dash frontend code
│   │   ├── main.py      # Dash app entry point
│   │   ├── components/  # UI components
│   │   └── pages/       # Page components
│   └── agents/          # AI processing agents
├── database/
│   └── init.sql         # Database initialization
├── docs/                # Detailed technical documentation
├── docker-compose.yml   # Development environment
├── requirements-backend.txt
├── requirements-frontend.txt
└── .env.example         # Environment template

---

🔧 Environment Configuration

Required Environment Variables

Copy .env.example to .env and configure:

# 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

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

---

📚 Documentation

All technical documentation is centralized in the /docs folder:

Core Documentation

• Development Setup - Complete environment setup with troubleshooting
• MVP Architecture - High-level system design and component overview
• API Specification - Complete REST API documentation with examples
• Database Design - Schema, security policies, and optimization

Process Documentation

• Git Branch Strategy - Version control workflow and team coordination
• Testing Strategy - Testing guidelines and automation setup
• Team Management - Team roles, processes, and standards

---

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

# Ensure .env file is in project root
ls -la .env

"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

Clean Restart

If you encounter persistent issues:

# Complete clean restart
docker-compose down -v
docker system prune -f
docker-compose up --build -d

---

🎯 Development Workflow

1. Starting Development

# Ensure latest code
git pull origin main

# Start environment
docker-compose up -d

# Verify all services
docker-compose ps
curl http://localhost:8000/health

2. Making Changes

# Backend changes auto-reload
# Frontend changes auto-reload
# Database changes require restart: docker-compose restart postgres

3. Testing Changes

# Run tests
docker-compose exec backend pytest

# Check logs
docker-compose logs -f backend

---

🚀 MVP Development Status

Current Phase: Foundation Setup ✅

• Project structure and documentation
• Docker development environment
• Database schema with RLS policies
• Environment configuration

Next Phase: Core Implementation 🚧

• User authentication system
• Application CRUD operations
• AI agents integration
• Frontend UI components

Future Phases 📋

• AI-powered research generation
• Resume optimization engine
• Cover letter generation
• Document editing interface
• Production deployment

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Ready to transform your job search? Let's build something amazing! 🚀