# Job Forge - AI-Powered Job Application Assistant

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com)
[![Dash](https://img.shields.io/badge/Dash-2.14+-purple.svg)](https://dash.plotly.com)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16+-blue.svg)](https://postgresql.org)

> **Job Forge** is a Python/FastAPI web application prototype that leverages AI to streamline the job application process through automated document generation, application tracking, and intelligent job matching.

## 🚀 Quick Start

### Docker Development (Recommended)
```bash
# Clone the repository
git clone https://github.com/yourusername/job-forge.git
cd job-forge

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys (Claude, OpenAI, JWT secret)

# Start development environment
cd docker
docker compose up -d

# Access the applications
# Frontend: http://localhost:8501
# Backend API: http://localhost:8000
# Database: localhost:5432
```

### Local Development Setup
```bash
# For local development and testing
pip install -r requirements.txt

# For development dependencies only
pip install -r dev-requirements.txt

# Run tests locally
python validate_tests.py    # Validate test structure
python run_tests.py        # Run API tests against Docker environment
pytest                     # Run full pytest suite (requires local services)
```

## 📚 Documentation Navigation

### 🏗️ **Architecture & Planning**
- [**System Architecture**](docs/jobforge_mvp_architecture.md) - Complete system overview and component breakdown
- [**API Specification**](docs/api_specification.md) - Comprehensive API endpoints and examples
- [**Database Design**](docs/database_design.md) - Schema design with RLS policies and performance optimization
- [**MVP Checklist**](docs/MVP_CHECKLIST.md) - Development progress tracking

### 🛠️ **Development**
- [**Development Setup**](docs/development_setup.md) - Environment setup and configuration
- [**Getting Started Guide**](docs/GETTING_STARTED.md) - Week-by-week implementation roadmap
- [**Coding Standards**](docs/development/coding_standards.md) - Python/FastAPI best practices
- [**Implementation Patterns**](docs/development/implementation_patterns.md) - Code templates and examples

### 🧪 **Testing & Quality**
- [**Testing Strategy**](docs/testing_strategy.md) - Comprehensive testing approach with pytest
- [**QA Procedures**](docs/testing/qa_procedures.md) - Quality assurance workflows
- [**Manual Testing**](docs/testing/manual_testing_guide.md) - User workflow validation procedures

### 🚢 **Deployment & Infrastructure**
- [**Server Deployment**](docs/infrastructure/server_deployment.md) - Direct server deployment procedures
- [**Docker Setup**](docs/infrastructure/docker_setup.md) - Containerization and orchestration
- [**Environment Configuration**](docs/infrastructure/environment_setup.md) - Production environment setup
- [**Monitoring & Logging**](docs/infrastructure/monitoring.md) - Observability and alerting

### 🔒 **Security & Operations**
- [**Security Guidelines**](docs/infrastructure/security_hardening.md) - Production security measures
- [**Backup Procedures**](docs/infrastructure/backup_procedures.md) - Data backup and recovery
- [**Git Workflow**](docs/git_branch_strategy.md) - Branching strategy and collaboration

### 🤖 **AI Integration**
- [**AI Services Setup**](docs/development/ai_integration.md) - Claude and OpenAI API integration
- [**Document Generation**](docs/development/document_generation.md) - Automated resume and cover letter creation
- [**Job Matching**](docs/development/job_matching.md) - AI-powered job recommendation system

## 🏛️ **Technology Stack**

### Backend
- **FastAPI** - Modern Python web framework
- **PostgreSQL 16** - Database with pgvector for AI embeddings
- **SQLAlchemy** - ORM with async support
- **Alembic** - Database migrations
- **Pydantic** - Data validation and serialization

### Frontend
- **Dash** - Interactive web applications
- **Mantine Components** - Modern UI component library
- **Plotly** - Data visualization
- **Bootstrap** - Responsive design framework

### AI & ML
- **Claude API** - Document generation and analysis
- **OpenAI API** - Embeddings and completions
- **pgvector** - Vector similarity search
- **Sentence Transformers** - Text embeddings

### Development & Deployment
- **Docker** - Containerization
- **Docker Compose** - Development orchestration
- **pytest** - Testing framework
- **Black** - Code formatting
- **Ruff** - Fast Python linter

## 🎯 **Core Features**

### ✨ **AI Document Generation**
- Automated cover letter creation based on job descriptions
- Resume optimization and tailoring
- Professional formatting and styling
- Multiple export formats (PDF, DOCX)

### 📊 **Application Tracking**
- Comprehensive job application management
- Application status tracking and timeline
- Interview scheduling and notes
- Follow-up reminders and notifications

### 🔍 **Job Matching**
- AI-powered job recommendation system
- Skills gap analysis and suggestions
- Salary insights and market data
- Company culture and fit analysis

### 👥 **Multi-User Support**
- Secure user authentication and authorization
- Data isolation with PostgreSQL RLS
- User profile and preference management
- Team collaboration features

## 🏃 **Development Workflow**

1. **Planning Phase** - Technical Lead defines architecture and specifications
2. **Implementation Phase** - Full-Stack Developer builds features
3. **Quality Assurance** - QA Engineer validates and tests
4. **Deployment Phase** - DevOps Engineer handles deployment

## 📋 **Project Status**

- [x] Project architecture and database design
- [x] Development environment setup
- [x] API specification and documentation
- [ ] Core backend API implementation
- [ ] Frontend Dash application
- [ ] AI service integrations
- [ ] Testing suite implementation
- [ ] Production deployment

## 🤝 **Team & Agents**

Job Forge uses specialized AI agents for development:

- **Technical Lead** - Architecture decisions and technical guidance
- **Full-Stack Developer** - FastAPI backend and Dash frontend implementation  
- **QA Engineer** - pytest testing and quality assurance
- **DevOps Engineer** - Docker deployment and server infrastructure

See [CLAUDE.md](CLAUDE.md) for complete team orchestration documentation.

## 📖 **Documentation Categories**

### 📚 **Getting Started**
Perfect for new developers joining the project:
- [Development Setup](docs/development_setup.md)
- [Getting Started Guide](docs/GETTING_STARTED.md)
- [MVP Checklist](docs/MVP_CHECKLIST.md)

### 🔧 **Implementation**
For active development work:
- [API Specification](docs/api_specification.md)
- [Database Design](docs/database_design.md)
- [System Architecture](docs/jobforge_mvp_architecture.md)

### 💡 **Future Features**
For managing new feature ideas and scope:
- [Feature Management Process](docs/future_features/)
- [Feature Ideas](docs/future_features/ideas/)
- [Under Review](docs/future_features/under_review/)
- [Approved Features](docs/future_features/approved/)

### 🧪 **Quality Assurance**
For testing and validation:
- [Testing Strategy](docs/testing_strategy.md)
- [QA Procedures](docs/testing/)
- [Manual Testing](docs/testing/)

### 🚀 **Deployment**
For production deployment:
- [Server Deployment](docs/infrastructure/)
- [Docker Setup](docs/infrastructure/)
- [Security Guidelines](docs/infrastructure/)

## 🛡️ **Security**

Job Forge implements comprehensive security measures:
- **Authentication**: Secure user authentication with JWT tokens
- **Authorization**: Role-based access control (RBAC)
- **Data Isolation**: PostgreSQL Row Level Security (RLS)
- **API Security**: Rate limiting and input validation
- **Encryption**: Data encryption at rest and in transit

## 📈 **Performance**

Optimized for performance and scalability:
- **Database**: Optimized queries with proper indexing
- **API**: Async FastAPI for high concurrency
- **Caching**: Redis for session and API response caching
- **CDN**: Static asset delivery optimization
- **Monitoring**: Application and infrastructure monitoring

## 🧪 **Testing**

Comprehensive testing strategy:
- **Unit Tests**: 80%+ coverage with pytest
- **Integration Tests**: API and database testing
- **End-to-End Tests**: User workflow validation
- **Performance Tests**: Load and stress testing
- **Security Tests**: Vulnerability scanning and validation

## 📊 **Monitoring & Analytics**

Built-in observability:
- **Application Monitoring**: Error tracking and performance metrics
- **Infrastructure Monitoring**: Server and database health
- **User Analytics**: Feature usage and user behavior
- **Security Monitoring**: Threat detection and response

## 🤖 **AI Integration**

Seamless AI service integration:
- **Claude API**: Advanced document generation and analysis
- **OpenAI API**: Embeddings and text completions
- **Vector Search**: Semantic job matching with pgvector
- **Error Handling**: Robust fallback and retry mechanisms

## 📱 **User Experience**

Modern and intuitive interface:
- **Responsive Design**: Mobile-first responsive layout
- **Interactive Components**: Rich Dash components with Mantine
- **Real-time Updates**: Live status updates and notifications
- **Accessible**: WCAG 2.1 AA compliance
- **Performance**: Fast loading and smooth interactions

## 🔧 **Development Tools**

Optimized development experience:
- **Hot Reload**: Real-time code changes with Docker
- **Code Quality**: Black formatting and Ruff linting
- **Type Safety**: Full type hints with mypy validation
- **Debugging**: Comprehensive logging and debugging tools
- **Testing**: Fast test execution with pytest

## 📞 **Support & Contributing**

- **Issues**: Report bugs and request features via GitHub Issues
- **Documentation**: Comprehensive documentation in `docs/` folder
- **Code Style**: Follow established Python/FastAPI best practices
- **Testing**: Maintain test coverage above 80%
- **Reviews**: All changes require code review and testing

## 📄 **License**

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

**Ready to start building?** 🚀

1. Follow the [Development Setup](docs/development_setup.md) guide
2. Check the [Getting Started](docs/GETTING_STARTED.md) roadmap
3. Review the [API Specification](docs/api_specification.md)
4. Start with the [MVP Checklist](docs/MVP_CHECKLIST.md)

For team coordination and agent management, see [CLAUDE.md](CLAUDE.md).