337 lines
8.8 KiB
Markdown
337 lines
8.8 KiB
Markdown
# ⚡ 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.
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://www.python.org/downloads/)
|
|
[](https://fastapi.tiangolo.com/)
|
|
[](https://www.postgresql.org/)
|
|
|
|
---
|
|
|
|
## 🚀 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
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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](#-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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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:
|
|
|
|
```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
|
|
```
|
|
|
|
### 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](docs/development_setup.md)** - Complete environment setup with troubleshooting
|
|
- **[MVP Architecture](docs/jobforge_mvp_architecture.md)** - High-level system design and component overview
|
|
- **[API Specification](docs/api_specification.md)** - Complete REST API documentation with examples
|
|
- **[Database Design](docs/database_design.md)** - Schema, security policies, and optimization
|
|
|
|
### Process Documentation
|
|
- **[Git Branch Strategy](docs/git_branch_strategy.md)** - Version control workflow and team coordination
|
|
- **[Testing Strategy](docs/testing_strategy.md)** - Testing guidelines and automation setup
|
|
- **[Team Management](docs/team_management_guide.md)** - Team roles, processes, and standards
|
|
|
|
---
|
|
|
|
## 🐛 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-"
|
|
|
|
# Ensure .env file is in project root
|
|
ls -la .env
|
|
```
|
|
|
|
#### "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
|
|
```
|
|
|
|
### Clean Restart
|
|
If you encounter persistent issues:
|
|
```bash
|
|
# Complete clean restart
|
|
docker-compose down -v
|
|
docker system prune -f
|
|
docker-compose up --build -d
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Development Workflow
|
|
|
|
### 1. Starting Development
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Backend changes auto-reload
|
|
# Frontend changes auto-reload
|
|
# Database changes require restart: docker-compose restart postgres
|
|
```
|
|
|
|
### 3. Testing Changes
|
|
```bash
|
|
# Run tests
|
|
docker-compose exec backend pytest
|
|
|
|
# Check logs
|
|
docker-compose logs -f backend
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 MVP Development Status
|
|
|
|
### Current Phase: Foundation Setup ✅
|
|
- [x] Project structure and documentation
|
|
- [x] Docker development environment
|
|
- [x] Database schema with RLS policies
|
|
- [x] 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](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! 🚀** |