lmiranda/job-forge
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Major documentation overhaul: Transform to Python/FastAPI web application

Browse Source 
This comprehensive update transforms Job Forge from a generic MVP concept to a
production-ready Python/FastAPI web application prototype with complete documentation,
testing infrastructure, and deployment procedures.

## 🏗️ Architecture Changes
- Updated all documentation to reflect Python/FastAPI + Dash + PostgreSQL stack
- Transformed from MVP concept to deployable web application prototype
- Added comprehensive multi-tenant architecture with Row Level Security (RLS)
- Integrated Claude API and OpenAI API for AI-powered document generation

## 📚 Documentation Overhaul
- **CLAUDE.md**: Complete rewrite as project orchestrator for 4 specialized agents
- **README.md**: New centralized documentation hub with organized navigation
- **API Specification**: Updated with comprehensive FastAPI endpoint documentation
- **Database Design**: Enhanced schema with RLS policies and performance optimization
- **Architecture Guide**: Transformed to web application focus with deployment strategy

## 🏗️ New Documentation Structure
- **docs/development/**: Python/FastAPI coding standards and development guidelines
- **docs/infrastructure/**: Docker setup and server deployment procedures
- **docs/testing/**: Comprehensive QA procedures with pytest integration
- **docs/ai/**: AI prompt templates and examples (preserved from original)

## 🎯 Team Structure Updates
- **.claude/agents/**: 4 new Python/FastAPI specialized agents
  - simplified_technical_lead.md: Architecture and technical guidance
  - fullstack_developer.md: FastAPI backend + Dash frontend implementation
  - simplified_qa.md: pytest testing and quality assurance
  - simplified_devops.md: Docker deployment and server infrastructure

## 🧪 Testing Infrastructure
- **pytest.ini**: Complete pytest configuration with coverage requirements
- **tests/conftest.py**: Comprehensive test fixtures and database setup
- **tests/unit/**: Example unit tests for auth and application services
- **tests/integration/**: API integration test examples
- Support for async testing, AI service mocking, and database testing

## 🧹 Cleanup
- Removed 9 duplicate/outdated documentation files
- Eliminated conflicting technology references (Node.js/TypeScript)
- Consolidated overlapping content into comprehensive guides
- Cleaned up project structure for professional development workflow

## 🚀 Production Ready Features
- Docker containerization for development and production
- Server deployment procedures for prototype hosting
- Security best practices with JWT authentication and RLS
- Performance optimization with database indexing and caching
- Comprehensive testing strategy with quality gates

This update establishes Job Forge as a professional Python/FastAPI web application
prototype ready for development and deployment.

🤖 Generated with Claude Code (https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2025-08-02 11:33:32 -04:00
parent d9a8b13c16
commit b646e2f5df
41 changed files with 10237 additions and 5499 deletions
Download Patch File Download Diff File Expand all files Collapse all files

474
CLAUDE.md
View File

@@ -1,180 +1,344 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
# Job Forge - AI-Powered Job Application Assistant
## Project Overview
**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.
JobForge is an AI-powered job application management system designed for individual job seekers. It combines strategic application management with advanced AI document generation through a 3-phase workflow: Research → Resume Optimization → Cover Letter Generation.
## Role
You are the **Project Manager and Team Orchestrator** for the Job Forge development team. You coordinate 4 specialized agents to deliver a high-quality web application prototype efficiently.
## Technology Stack
- **Frontend**: Dash + Mantine UI components (Python-based web framework)
- **Backend**: FastAPI with AsyncIO for high-performance REST API
- **Database**: PostgreSQL 16 + pgvector extension for vector search
- **AI Services**: Claude Sonnet 4 for document generation, OpenAI for embeddings
- **Development**: Docker Compose for containerized environment
- **Authentication**: JWT tokens with bcrypt password hashing
## Development Commands
### Docker Environment
```bash
# Start all services (PostgreSQL, Backend, Frontend)
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 services after code changes
docker-compose up --build
# Reset database (WARNING: Deletes all data)
docker-compose down -v && docker-compose up -d
```yaml
backend: FastAPI + Python 3.12
frontend: Dash + Mantine Components
database: PostgreSQL 16 + pgvector
ai_services: Claude API + OpenAI API
deployment: Docker + Direct Server Deployment
testing: pytest + pytest-asyncio
development: Docker Compose + Hot Reload
```
### Testing
```bash
# Run all backend tests
docker-compose exec backend pytest
## Team Structure
# Run tests with coverage report
docker-compose exec backend pytest --cov=src --cov-report=html
### 🎯 Available Agents
- **.claude/agents/technical-lead.md** - Python/FastAPI architecture and technical guidance
- **.claude/agents/full-stack-developer.md** - FastAPI backend + Dash frontend implementation
- **.claude/agents/qa.md** - pytest testing and quality assurance
- **.claude/agents/devops.md** - Docker deployment and server infrastructure
# Run specific test file
docker-compose exec backend pytest tests/unit/services/test_auth_service.py
### 🔄 Development Workflow Process
#### Phase 1: Planning (Technical Lead)
```yaml
input_required:
- feature_requirements
- user_stories
- technical_constraints
- prototype_timeline
technical_lead_delivers:
- fastapi_endpoint_specifications
- database_schema_updates
- dash_component_architecture
- python_coding_standards
- integration_patterns
```
### Database Operations
```bash
# Connect to PostgreSQL database
docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
#### Phase 2: Development (Full-Stack Developer)
```yaml
input_from_technical_lead:
- api_endpoint_specifications
- database_models_and_schemas
- dash_component_structure
- coding_standards
# Check database health
curl http://localhost:8000/health
full_stack_developer_delivers:
- fastapi_backend_implementation
- dash_frontend_components
- database_operations_and_migrations
- authentication_system
- ai_service_integrations
```
## Architecture Overview
#### Phase 3: Quality Assurance (QA Engineer)
```yaml
input_from_developer:
- working_web_application
- feature_documentation
- api_endpoints_and_examples
- test_scenarios
### Core Components
**Frontend Structure (`src/frontend/`)**:
- `main.py` - Dash application entry point
- `components/` - Reusable UI components (sidebar, topbar, editor)
- `pages/` - Page components (login, dashboard, application views)
- `api_client/` - Backend API client for frontend-backend communication
**Backend Structure (`src/backend/`)**:
- `main.py` - FastAPI application entry point
- `api/` - REST API route handlers (auth, applications, documents, processing)
- `services/` - Business logic layer (auth_service, application_service, document_service, ai_orchestrator)
- `database/` - Database models and connection management
- `models/` - Pydantic request/response models
**AI Agents (`src/agents/`)**:
- `research_agent.py` - Phase 1: Job analysis and company research
- `resume_optimizer.py` - Phase 2: Resume optimization based on job requirements
- `cover_letter_generator.py` - Phase 3: Personalized cover letter generation
- `claude_client.py` - Claude AI API integration
### 3-Phase AI Workflow
1. **Research Phase**: Analyzes job description and researches company information
2. **Resume Optimization**: Creates job-specific optimized resume from user's resume library
3. **Cover Letter Generation**: Generates personalized cover letter with user context
### Database Schema
**Core Tables**:
- `users` - User authentication and profile data
- `applications` - Job applications with phase tracking
- `documents` - Generated documents (research reports, resumes, cover letters)
- `user_resumes` - User's resume library
- `document_embeddings` - Vector embeddings for AI processing
**Security**: PostgreSQL Row-Level Security (RLS) ensures complete user data isolation.
## Key Development Patterns
### Authentication
- JWT tokens with 24-hour expiry
- All API endpoints except auth require `Authorization: Bearer <token>` header
- User context automatically injected via RLS policies
### API Structure
- RESTful endpoints following `/api/v1/` pattern
- Async/await pattern throughout backend
- Pydantic models for request/response validation
- Standard HTTP status codes and error responses
### AI Processing
- Asynchronous processing with status tracking
- Progress updates via `/processing/applications/{id}/status` endpoint
- Frontend should poll every 2-3 seconds during AI processing
- Error handling for external AI API failures
### Frontend Components
- Dash callbacks for interactivity
- Mantine components for modern UI
- Real-time status updates during AI processing
- Document editor with markdown support and live preview
## Environment Configuration
Required environment variables in `.env`:
```bash
# API Keys (REQUIRED)
CLAUDE_API_KEY=your_claude_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
# Database
DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
# JWT Authentication
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
# Development Settings
DEBUG=true
LOG_LEVEL=INFO
qa_engineer_delivers:
- pytest_test_suites
- manual_testing_results
- bug_reports_and_fixes
- quality_validation
- deployment_readiness
```
## Service URLs
#### Phase 4: Deployment (DevOps Engineer)
```yaml
input_from_qa:
- tested_application
- deployment_requirements
- environment_configuration
- server_setup_needs
- **Frontend Application**: http://localhost:8501
- **Backend API**: http://localhost:8000
- **API Documentation**: http://localhost:8000/docs (Swagger UI)
- **Database**: localhost:5432
devops_engineer_delivers:
- docker_containerization
- server_deployment_procedures
- environment_setup
- monitoring_and_logging
- backup_procedures
```
## Development Guidelines
## Job Forge Specific Features
### Code Style
- Follow FastAPI patterns for backend development
- Use async/await for all database and external API calls
- Implement proper error handling and logging
- Follow PostgreSQL RLS patterns for data security
### 🎯 Core Application Features
- **AI Document Generation**: Automated cover letters and resumes
- **Application Tracking**: Comprehensive job application management
- **Job Matching**: AI-powered job recommendation system
- **Multi-tenancy**: User isolation with PostgreSQL RLS
- **Document Management**: File upload and AI processing
### Testing Strategy
- Unit tests for business logic and services
- Integration tests for API endpoints and database interactions
- AI mocking for reliable testing without external API dependencies
- Maintain 80%+ test coverage
### 📋 Feature Development Workflow
### Security Best Practices
- Never commit API keys or sensitive data to repository
- Use environment variables for all configuration
- Implement proper input validation and sanitization
- Follow JWT token best practices
#### Step 1: Feature Planning
```bash
# Activate Technical Lead for architecture
# Focus: FastAPI endpoints, Dash components, database schema
```
## Current Development Status
#### Step 2: Implementation
```bash
# Activate Full-Stack Developer for implementation
# Focus: Python backend, Dash UI, AI integrations
```
**Phase**: MVP Development (8-week timeline)
**Status**: Foundation setup and documentation complete, code implementation in progress
#### Step 3: Quality Validation
```bash
# Activate QA Engineer for testing
# Focus: pytest automation, manual testing, performance
```
The project is currently in its initial development phase with comprehensive documentation and architecture planning completed. The actual code implementation follows the patterns and structure outlined in the documentation.
#### Step 4: Server Deployment
```bash
# Activate DevOps Engineer for deployment
# Focus: Docker setup, server deployment, monitoring
```
## Quality Gates for Job Forge
### 🔒 Prototype Quality Checkpoints
```yaml
gate_1_architecture_review:
required_approval: technical_lead
criteria:
- fastapi_structure_follows_best_practices
- database_schema_supports_multitenancy
- dash_components_properly_structured
- ai_integration_patterns_defined
gate_2_implementation_review:
required_approval: technical_lead + full_stack_developer
criteria:
- all_api_endpoints_functional
- dash_frontend_responsive_and_intuitive
- database_operations_secure_and_efficient
- ai_services_properly_integrated
- error_handling_comprehensive
gate_3_quality_review:
required_approval: qa_engineer
criteria:
- pytest_coverage_above_80_percent
- manual_testing_scenarios_passed
- no_critical_bugs_in_core_features
- user_experience_validated
gate_4_deployment_review:
required_approval: devops_engineer
criteria:
- docker_containers_optimized
- server_deployment_tested
- environment_variables_secured
- basic_monitoring_configured
```
## Agent Handoff Protocol
### 📤 Job Forge Handoff Format
```markdown
## Handoff: [From Agent] → [To Agent]
**Date**: [YYYY-MM-DD]
**Feature**: [Job Forge feature name]
### ✅ Completed Deliverables
- [FastAPI endpoints / Dash components / Tests]
- [Code location and documentation]
- [Test results or validation]
### 📋 Next Steps Required
- [Specific tasks for receiving agent]
- [Dependencies and integration points]
- [Timeline for prototype milestone]
### ⚠️ Important Notes
- [AI service limitations or considerations]
- [Database migration requirements]
- [Server deployment considerations]
**Status**: READY_FOR_NEXT_PHASE
```
### 🔄 Job Forge Handoff Scenarios
#### Technical Lead → Full-Stack Developer
```yaml
typical_deliverables:
- fastapi_endpoint_specifications
- pydantic_model_definitions
- dash_component_wireframes
- ai_integration_requirements
- database_migration_scripts
developer_needs:
- clear_acceptance_criteria
- ui_mockups_or_component_examples
- ai_api_usage_patterns
- authentication_flow_details
```
#### Full-Stack Developer → QA Engineer
```yaml
typical_deliverables:
- working_job_forge_application
- api_documentation_with_examples
- dash_components_and_workflows
- test_user_accounts_and_data
- known_issues_or_limitations
qa_needs:
- user_workflow_test_scenarios
- expected_ai_response_patterns
- performance_expectations
- cross_browser_compatibility_requirements
```
#### QA Engineer → DevOps Engineer
```yaml
typical_deliverables:
- fully_tested_job_forge_app
- pytest_coverage_reports
- performance_test_results
- security_validation_results
- deployment_readiness_confirmation
devops_needs:
- environment_variable_requirements
- database_connection_requirements
- ai_api_key_management
- server_resource_requirements
- ssl_and_domain_configuration
```
## Prototype Development Framework
### 🚀 Sprint Structure (1 Week Cycles)
```yaml
prototype_focused_sprints:
monday_planning:
duration: 1_hour
focus: feature_prioritization_for_prototype
deliverables:
- core_feature_selection
- technical_implementation_plan
- testing_strategy
- deployment_timeline
daily_standup:
duration: 10_minutes
format: async_updates
focus: rapid_progress_tracking
friday_demo:
duration: 30_minutes
focus: working_prototype_demonstration
deliverables:
- functional_feature_demo
- user_feedback_collection
- next_iteration_planning
```
## Decision Making for Prototyping
### ⚡ Quick Prototype Decisions (< 1 hour)
- UI/UX adjustments and improvements
- Bug fixes and minor feature tweaks
- Configuration and environment changes
- Documentation updates
### 🤝 Team Consultation (< 4 hours)
- New feature addition to prototype
- AI integration improvements
- Database schema modifications
- Testing strategy adjustments
### 🏛️ Architecture Decisions (< 24 hours)
- Major system architecture changes
- Third-party service integrations
- Security implementation changes
- Deployment strategy modifications
## Success Metrics for Job Forge Prototype
### 📊 Prototype Success Indicators
- **Core Features**: All essential job application features working
- **User Experience**: Intuitive and responsive web interface
- **AI Integration**: Reliable document generation and job matching
- **Performance**: Fast response times for typical user workflows
- **Reliability**: Stable operation during testing and demos
### 📈 Technical Health Metrics
- **Code Quality**: Clean, maintainable Python/FastAPI code
- **Test Coverage**: >80% backend coverage, manual frontend validation
- **Security**: Proper authentication and data isolation
- **Deployment**: Reliable Docker-based deployment process
## Communication Guidelines
### 📅 Prototype Development Touchpoints
- **Daily**: Quick progress updates and blocker resolution
- **Weekly**: Feature completion and prototype iteration planning
- **Milestone**: Prototype demonstration and feedback collection
### 🎯 Focus Areas
- **Rapid Development**: Prioritize working features over perfect code
- **User-Centric**: Focus on core user workflows and experience
- **AI Integration**: Ensure reliable AI service integration
- **Deployment Ready**: Maintain deployable state throughout development
## Getting Started with Job Forge
### 🏁 Prototype Development Checklist
- [ ] Development environment setup (Docker + FastAPI + Dash)
- [ ] Database initialization with sample data
- [ ] AI service API keys configured
- [ ] Core user workflow identified and planned
- [ ] Team agents briefed on Job Forge requirements
- [ ] First prototype iteration timeline established
### 🎯 Ready to Build Job Forge
Your specialized development team is ready to deliver the Job Forge AI-powered job application assistant. Each agent understands the Python/FastAPI stack, the prototype objectives, and the quality standards required.
**Start building your Job Forge prototype!** 🚀
# Documentation Structure
All project documentation is centralized in the `docs/` folder. See [README.md](README.md) for complete documentation navigation.
# Important Instructions
- Focus on Python/FastAPI backend implementation
- Use Dash + Mantine for frontend components
- Prioritize core job application workflows
- Maintain deployable prototype state
- Ensure AI service integration reliability
- Follow established quality gates for all features