Transform your job search with intelligent document generation and strategic application management. JobForge leverages advanced AI to create tailored resumes and cover letters while streamlining your entire application workflow.

🎯 Project Overview

What is JobForge?

JobForge is an AI-powered job application management system designed to streamline and optimize the job search process. Built for individual job seekers, it combines strategic application management with advanced AI document generation to maximize your chances of landing interviews.

Key Features (MVP)

✨ 3-Phase AI Workflow

Research Phase: Automated job description analysis and company research
Resume Optimization: Multi-resume synthesis tailored to specific job requirements
Cover Letter Generation: Personalized cover letters with authentic voice preservation

🎨 Modern Interface

Professional web application built with Dash + Mantine components
Intuitive sidebar navigation and document management
Real-time processing status and progress tracking

🔒 Secure & Private

Complete user data isolation with PostgreSQL Row-Level Security
Local document storage with full user control
JWT-based authentication system

🤖 AI-Powered Intelligence

Claude Sonnet 4 for document generation and analysis
OpenAI embeddings for semantic document matching
Vector database for intelligent insights and recommendations

🏗️ Architecture Overview

Technology Stack

Component	Technology	Purpose
Frontend	Dash + Mantine	Modern, responsive web interface
Backend	FastAPI + AsyncIO	High-performance REST API
Database	PostgreSQL 16 + pgvector	Data persistence with vector search
AI Services	Claude Sonnet 4, OpenAI	Document generation and analysis
Development	Docker Compose	Containerized development environment
Authentication	JWT + bcrypt	Secure user authentication

System Architecture

graph TB
    subgraph "Frontend Layer"
        UI[Dash + Mantine UI]
        COMP[Reusable Components]
    end
    
    subgraph "Backend API"
        API[FastAPI Rest API]
        AUTH[JWT Authentication]
        SERVICES[Business Services]
    end
    
    subgraph "AI Processing"
        CLAUDE[Claude Sonnet 4]
        OPENAI[OpenAI Embeddings]
        AGENTS[AI Agents]
    end
    
    subgraph "Data Layer"
        PG[(PostgreSQL + pgvector)]
        REDIS[(Redis Cache)]
    end
    
    UI --> API
    API --> AUTH
    API --> SERVICES
    SERVICES --> AGENTS
    AGENTS --> CLAUDE
    AGENTS --> OPENAI
    SERVICES --> PG
    API --> REDIS

🚀 Quick Start

Prerequisites

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

1. Clone & Setup

# Clone the repository
git clone https://github.com/your-org/jobforge-mvp.git
cd jobforge-mvp

# Copy environment template
cp .env.example .env

# Add your API keys to .env file
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. Access the Application

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

4. Create Your First Application

Register a new account at http://localhost:8501
Upload your resume(s) to the resume library
Create a new job application with company details and job description
Watch the AI generate your research report, optimized resume, and cover letter
Edit and refine the generated documents as needed

📚 Documentation

📖 Core Documentation

Document	Description	For
📋 MVP Architecture	High-level system design and component overview	All team members
🔧 Development Setup	Complete environment setup with troubleshooting	Developers
🌿 Git Branch Strategy	Version control workflow and team coordination	All team members

🛠️ Technical Documentation

Document	Description	For
🔌 API Specification	Complete REST API documentation with examples	Backend developers
🗄️ Database Design	Schema, security policies, and optimization	Backend developers
🧪 Testing Strategy	Testing guidelines and automation setup	All developers

📝 Additional Resources

📊 Project Roadmap - Development timeline and milestones
🤝 Contributing Guidelines - How to contribute to the project
❓ FAQ - Common questions and answers

🔄 Development Workflow

Branch Strategy

We use a Git Flow approach with the following branches:

main - Production-ready code (protected)
develop - Integration branch for completed features
feature/* - Individual feature development
hotfix/* - Emergency production fixes
release/* - Release preparation and testing

Example feature branch names:

feature/backend-user-authentication
feature/frontend-application-sidebar
feature/ai-claude-integration
feature/database-rls-policies

See our Git Branch Strategy for detailed workflows.

Development Process

Start Feature: Create branch from develop
Implement: Follow coding standards and write tests
Test: Ensure all tests pass and CI/CD checks succeed
Review: Submit PR with detailed description
Merge: Merge to develop after approval
Deploy: Automatic deployment to staging environment

🏃‍♂️ Project Status

Current Phase: MVP Development

Timeline: 8 weeks (July - August 2025)
Status: 🚧 In Development
Target: Production-ready MVP for personal use and concept validation

MVP Milestones

Week	Milestone	Status
1-2	Foundation & Infrastructure	🚧 In Progress
3-4	User Authentication & Application CRUD	⏳ Planned
5-6	AI Agents Integration	⏳ Planned
7-8	Frontend Polish & Release	⏳ Planned

Feature Completion

Project setup and documentation
Docker development environment
User authentication system
Application creation and management
AI-powered research generation
Resume optimization engine
Cover letter generation
Document editing interface
Production deployment

🧪 Testing

Testing Strategy

We maintain high code quality through comprehensive testing:

Unit Tests: Business logic and services (80%+ coverage)
Integration Tests: API endpoints and database interactions
Manual Testing: Complete user workflows and edge cases
AI Mocking: Reliable testing without external API dependencies

Running Tests

# Run all tests
docker-compose exec backend pytest

# Run with coverage report
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

See Testing Strategy for detailed testing guidelines.

🚀 Deployment

Development Environment

# Start development environment
docker-compose up -d

# View service logs
docker-compose logs -f [service_name]

# Stop environment
docker-compose down

Production Deployment

Production deployment instructions will be added as we approach MVP completion. The current focus is on local development and testing.

🤝 Contributing

Getting Started

Read the Documentation: Start with Development Setup
Set Up Environment: Follow the quick start guide above
Choose a Task: Check open issues or discuss new features
Create Feature Branch: Follow our Git Branch Strategy
Submit Pull Request: Include tests and documentation updates

Development Standards

Code Style: Black formatter, isort imports, type hints required
Testing: Write tests for new functionality, maintain coverage
Documentation: Update relevant docs for user-facing changes
Security: Never commit API keys or sensitive data

Pull Request Process

Create feature branch from develop
Implement changes with tests
Ensure all CI/CD checks pass
Submit PR with detailed description
Address code review feedback
Merge after approval

📊 Roadmap

Phase 1: MVP (Current - August 2025)

Goal: Production-ready job application management tool for personal use

Key Features:

Complete 3-phase AI workflow
Professional web interface
Secure user authentication
Document management and editing

Phase 2: SaaS Platform (September 2025+)

Goal: Multi-tenant SaaS platform with subscription billing

Planned Features:

Subscription management and billing
Usage analytics and insights
Advanced AI features and learning
Post-application tracking (interviews, responses)
Mobile application

Phase 3: Advanced Features (Future)

Goal: Enterprise-grade job application platform

Planned Features:

Multi-language support
Integration with job boards and ATS systems
Advanced analytics and success prediction
White-label solutions for career coaches

❓ FAQ

General Questions

Q: What makes JobForge different from other job application tools?
A: JobForge combines AI-powered document generation with strategic application management. Unlike simple trackers, it actively helps create better applications using advanced AI analysis and multi-resume optimization.

Q: Is JobForge free to use?
A: The MVP is designed for personal use and concept validation. Future SaaS plans will include both free and paid tiers with different feature sets.

Q: What AI models does JobForge use?
A: We use Claude Sonnet 4 for document generation and analysis, plus OpenAI embeddings for semantic search and document matching.

Technical Questions

Q: Can I run JobForge without Docker?
A: While possible, Docker is strongly recommended for consistent development environments. Manual setup instructions may be added in the future.

Q: How secure is my job application data?
A: Very secure. We use PostgreSQL Row-Level Security for complete user data isolation, JWT authentication, and all sensitive data is encrypted at rest.

Q: Can I contribute to JobForge development?
A: Yes! Check our Contributing Guidelines and Development Setup to get started.

Development Questions

Q: What's the recommended development workflow?
A: Follow our Git Branch Strategy - create feature branches from develop, implement with tests, submit PRs for review.

Q: How do I add a new API endpoint?
A: See our API Specification for examples and patterns, then follow the testing guidelines in Testing Strategy.

Q: Where can I find the database schema?
A: Complete schema documentation is in Database Design including security policies and performance optimization.

📄 License

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

🙏 Acknowledgments

Claude Sonnet 4 by Anthropic for advanced AI document generation
OpenAI for embedding models and semantic search capabilities
FastAPI community for the excellent async web framework
Dash and Plotly teams for the modern Python web framework
PostgreSQL and pgvector for robust data storage and vector search

📞 Support & Contact

Development Team

For development questions, bug reports, or feature requests:

Issues: Use GitHub/Gitea issues for bug reports and feature requests
Discussions: Use GitHub/Gitea discussions for general questions
Documentation: Check the docs folder for detailed guides

Getting Help

Check Documentation: Most questions are answered in our comprehensive docs
Search Issues: Look for existing issues or discussions
Ask Questions: Create new discussions for general questions
Report Bugs: Use issue templates for bug reports

Made with ❤️ for job seekers everywhere

Transform your job search. Forge your path to success.