initial setup
This commit is contained in:
421
README.md
421
README.md
@@ -1,3 +1,420 @@
|
||||
# job-forge
|
||||
# ⚡ JobForge MVP
|
||||
|
||||
A tool to help with job applications.
|
||||
**AI-Powered Job Application Management System**
|
||||
|
||||
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.
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://www.python.org/downloads/)
|
||||
[](https://fastapi.tiangolo.com/)
|
||||
[](https://www.postgresql.org/)
|
||||
[](https://www.docker.com/)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 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
|
||||
|
||||
```mermaid
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
1. Register a new account at http://localhost:8501
|
||||
2. Upload your resume(s) to the resume library
|
||||
3. Create a new job application with company details and job description
|
||||
4. Watch the AI generate your research report, optimized resume, and cover letter
|
||||
5. Edit and refine the generated documents as needed
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
### 📖 Core Documentation
|
||||
|
||||
| Document | Description | For |
|
||||
|----------|-------------|-----|
|
||||
| **[📋 MVP Architecture](docs/mvp-architecture.md)** | High-level system design and component overview | All team members |
|
||||
| **[🔧 Development Setup](docs/development-setup.md)** | Complete environment setup with troubleshooting | Developers |
|
||||
| **[🌿 Git Branch Strategy](docs/git-branch-strategy.md)** | Version control workflow and team coordination | All team members |
|
||||
|
||||
### 🛠️ Technical Documentation
|
||||
|
||||
| Document | Description | For |
|
||||
|----------|-------------|-----|
|
||||
| **[🔌 API Specification](docs/api-specification.md)** | Complete REST API documentation with examples | Backend developers |
|
||||
| **[🗄️ Database Design](docs/database-design.md)** | Schema, security policies, and optimization | Backend developers |
|
||||
| **[🧪 Testing Strategy](docs/testing-strategy.md)** | Testing guidelines and automation setup | All developers |
|
||||
|
||||
### 📝 Additional Resources
|
||||
|
||||
- **[📊 Project Roadmap](#roadmap)** - Development timeline and milestones
|
||||
- **[🤝 Contributing Guidelines](#contributing)** - How to contribute to the project
|
||||
- **[❓ FAQ](#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:**
|
||||
```bash
|
||||
feature/backend-user-authentication
|
||||
feature/frontend-application-sidebar
|
||||
feature/ai-claude-integration
|
||||
feature/database-rls-policies
|
||||
```
|
||||
|
||||
See our **[Git Branch Strategy](docs/git-branch-strategy.md)** for detailed workflows.
|
||||
|
||||
### Development Process
|
||||
|
||||
1. **Start Feature:** Create branch from `develop`
|
||||
2. **Implement:** Follow coding standards and write tests
|
||||
3. **Test:** Ensure all tests pass and CI/CD checks succeed
|
||||
4. **Review:** Submit PR with detailed description
|
||||
5. **Merge:** Merge to `develop` after approval
|
||||
6. **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
|
||||
|
||||
- [x] Project setup and documentation
|
||||
- [x] 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
|
||||
|
||||
```bash
|
||||
# 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](docs/testing-strategy.md)** for detailed testing guidelines.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### Development Environment
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
1. **Read the Documentation:** Start with [Development Setup](docs/development-setup.md)
|
||||
2. **Set Up Environment:** Follow the quick start guide above
|
||||
3. **Choose a Task:** Check open issues or discuss new features
|
||||
4. **Create Feature Branch:** Follow our [Git Branch Strategy](docs/git-branch-strategy.md)
|
||||
5. **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
|
||||
|
||||
1. Create feature branch from `develop`
|
||||
2. Implement changes with tests
|
||||
3. Ensure all CI/CD checks pass
|
||||
4. Submit PR with detailed description
|
||||
5. Address code review feedback
|
||||
6. Merge after approval
|
||||
|
||||
---
|
||||
|
||||
## 📊 Roadmap {#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 {#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](#contributing) and [Development Setup](docs/development-setup.md) to get started.
|
||||
|
||||
### Development Questions
|
||||
|
||||
**Q: What's the recommended development workflow?**
|
||||
A: Follow our [Git Branch Strategy](docs/git-branch-strategy.md) - 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](docs/api-specification.md) for examples and patterns, then follow the testing guidelines in [Testing Strategy](docs/testing-strategy.md).
|
||||
|
||||
**Q: Where can I find the database schema?**
|
||||
A: Complete schema documentation is in [Database Design](docs/database-design.md) including security policies and performance optimization.
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](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](docs/) folder for detailed guides
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. **Check Documentation:** Most questions are answered in our comprehensive docs
|
||||
2. **Search Issues:** Look for existing issues or discussions
|
||||
3. **Ask Questions:** Create new discussions for general questions
|
||||
4. **Report Bugs:** Use issue templates for bug reports
|
||||
|
||||
---
|
||||
|
||||
**Made with ❤️ for job seekers everywhere**
|
||||
|
||||
*Transform your job search. Forge your path to success.*
|
||||
Reference in New Issue
Block a user