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

378
docs/jobforge_mvp_architecture.md
View File

@@ -1,47 +1,48 @@
# JobForge MVP - Core Job Application Module
# Job Forge - Python/FastAPI Web Application Architecture
**Version:** 1.0.0 MVP
**Version:** 1.0.0 Prototype
**Status:** Development Phase 1
**Date:** July 2025
**Scope:** Core job application workflow with essential features
**Target:** Personal use for concept validation and testing
**Date:** August 2025
**Scope:** AI-powered job application management web application
**Target:** Prototype development for server deployment
---
## 📋 MVP Scope & Objectives
## 📋 Application Scope & Objectives
### Core Functionality
- **User Authentication**: Basic login/signup system
- **Job Application Creation**: Add new applications with job description and URL
- **3-Phase AI Workflow**: Research → Resume → Cover Letter generation
- **Document Management**: View and edit generated documents
- **Navigation Interface**: Sidebar + top bar for seamless workflow navigation
### Core Web Application Features
- **User Authentication**: JWT-based secure authentication system
- **Job Application Management**: Full CRUD operations for job applications
- **AI-Powered Document Generation**: Automated cover letter and resume optimization
- **Web Interface**: Modern responsive web interface using Dash + Mantine
- **Multi-tenant Architecture**: Secure user data isolation with RLS
### MVP Goals
- Validate core AI workflow effectiveness
- Test user experience with Dash + Mantine interface
- Prove concept with personal job application journey
- Establish foundation for Phase 2 (post-application features)
### Development Goals
- Deploy functional prototype to personal server
- Validate AI workflow effectiveness for job applications
- Test web application performance and user experience
- Establish scalable architecture for future enhancements
- Demonstrate full-stack Python/FastAPI capabilities
---
## 🏗️ MVP Architecture
## 🏗️ Web Application Architecture
### System Overview
```mermaid
graph TB
subgraph "Frontend (Dash + Mantine)"
UI[Main UI]
SIDEBAR[Application Sidebar]
TOPBAR[Navigation Top Bar]
subgraph "Web Frontend (Dash + Mantine)"
UI[Dashboard Interface]
FORMS[Application Forms]
EDITOR[Document Editor]
VIEWER[Document Viewer]
end
subgraph "Backend API (FastAPI)"
AUTH[Authentication]
APP[Application Service]
AI[AI Orchestrator]
DOC[Document Service]
AUTH[JWT Authentication]
CRUD[Application CRUD]
AI[AI Service Layer]
FILES[Document Management]
end
subgraph "AI Agents"
@@ -61,14 +62,15 @@ graph TB
end
UI --> AUTH
UI --> APP
UI --> DOC
APP --> AI
FORMS --> CRUD
EDITOR --> FILES
VIEWER --> FILES
CRUD --> AI
AI --> RESEARCH
AI --> RESUME
AI --> COVER
APP --> PG
DOC --> FILES
CRUD --> PG
FILES --> PG
RESEARCH --> CLAUDE
RESUME --> CLAUDE
COVER --> CLAUDE
@@ -77,40 +79,49 @@ graph TB
---
## 🔐 User Authentication (MVP)
## 🔐 User Authentication (Web Application)
### Simple Authentication System
### JWT-Based Authentication System
```python
class AuthenticationService:
"""Basic user authentication for MVP"""
"""JWT-based authentication for web application"""
async def register_user(self, email: str, password: str, name: str) -> User:
"""Register new user account"""
async def register_user(self, user_data: UserCreate) -> User:
"""Register new user account with validation"""
async def authenticate_user(self, email: str, password: str) -> AuthResult:
"""Login user and return JWT token"""
async def authenticate_user(self, credentials: UserLogin) -> AuthResult:
"""Authenticate user and return JWT access token"""
async def verify_token(self, token: str) -> User:
"""Verify JWT token and return user"""
"""Verify JWT token and return authenticated user"""
async def logout_user(self, user_id: str) -> None:
"""Logout user session"""
async def refresh_token(self, refresh_token: str) -> AuthResult:
"""Refresh JWT access token"""
def create_access_token(self, user_id: str) -> str:
"""Create JWT access token with expiration"""
```
### Database Schema (Users)
```sql
-- Basic user table for MVP
-- User table with enhanced security
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
full_name VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
first_name VARCHAR(100) NOT NULL,
last_name VARCHAR(100) NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- Enable basic row level security
-- Enable row level security for multi-tenancy
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
-- Create index for performance
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_active ON users(is_active);
```
---
@@ -558,157 +569,208 @@ CREATE POLICY user_own_resumes ON user_resumes FOR ALL USING (user_id = current_
---
## 🚀 MVP Development Plan
## 🚀 Web Application Development Plan
### Development Phases
#### **Week 1-2: Foundation Setup**
- Docker development environment
- PostgreSQL database with basic schema
- FastAPI backend with authentication endpoints
- Basic Dash + Mantine frontend structure
#### **Phase 1: Infrastructure & Authentication (Weeks 1-2)**
- Docker containerization for development and production
- PostgreSQL 16 with pgvector extension setup
- FastAPI backend with JWT authentication
- Row Level Security (RLS) implementation
- Basic CI/CD pipeline setup
#### **Week 3-4: Core Application Module**
- Application creation and listing
- Database integration with user isolation
- Basic sidebar and navigation UI
- Application status tracking
#### **Phase 2: Core Web Application (Weeks 3-4)**
- Dash + Mantine responsive web interface
- Application CRUD operations with API endpoints
- User dashboard and application management
- Database integration with async operations
- Multi-tenant data isolation
#### **Week 5-6: AI Workflow Implementation**
- Research Agent with Claude integration
- Resume Optimizer with portfolio handling
- Cover Letter Generator with user context
- Document storage and retrieval system
#### **Phase 3: AI Integration (Weeks 5-6)**
- Claude API integration for document generation
- OpenAI API for embeddings and analysis
- Async AI service layer implementation
- Error handling and retry mechanisms
- AI service rate limiting and monitoring
#### **Week 7-8: Frontend Polish & Integration**
- Document editor with markdown support
- Real-time status updates during AI processing
- Phase navigation and progress tracking
- Error handling and user feedback
#### **Phase 4: Production Deployment (Weeks 7-8)**
- Server deployment with Docker Compose
- Nginx reverse proxy and SSL configuration
- Database backup and monitoring setup
- Performance optimization and caching
- Security hardening and testing
### MVP Success Criteria
- ✅ User can register/login securely
- ✅ User can create job applications with description/URL
- ✅ AI generates research report automatically
- ✅ AI optimizes resume based on job requirements
- ✅ AI generates cover letter with user context
- ✅ User can view and edit all generated documents
- ✅ Smooth navigation between application phases
- ✅ Data persisted securely with user isolation
### Prototype Success Criteria
- ✅ Secure multi-user web application deployed to server
- ✅ JWT-based authentication with user registration/login
- ✅ Full CRUD operations for job applications
- ✅ AI-powered cover letter generation via web interface
- ✅ Responsive web UI with modern UX design
- ✅ Secure data storage with user isolation (RLS)
- ✅ Production-ready deployment with monitoring
- ✅ Scalable architecture for future enhancements
---
## 🐳 Docker Development Setup
## 🐳 Docker Production Deployment
### Development Environment
### Production Environment
```yaml
# docker-compose.yml
version: '3.8'
services:
postgres:
image: pgvector/pgvector:pg16
environment:
POSTGRES_DB: jobforge_mvp
POSTGRES_USER: jobforge_user
POSTGRES_PASSWORD: jobforge_password
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
- ./database/init.sql:/docker-entrypoint-initdb.d/init.sql
backend:
# FastAPI + Dash Web Application
jobforge-app:
build:
context: .
dockerfile: Dockerfile.backend
ports:
- "8000:8000"
dockerfile: Dockerfile
target: production
container_name: jobforge-app
environment:
- DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
- DATABASE_URL=postgresql://jobforge:${DB_PASSWORD}@postgres:5432/jobforge
- CLAUDE_API_KEY=${CLAUDE_API_KEY}
- OPENAI_API_KEY=${OPENAI_API_KEY}
- JWT_SECRET=${JWT_SECRET}
- DEBUG=false
- LOG_LEVEL=INFO
volumes:
- ./src:/app/src
- ./uploads:/app/uploads
- ./logs:/var/log/jobforge
depends_on:
- postgres
command: uvicorn src.backend.main:app --host 0.0.0.0 --port 8000 --reload
postgres:
condition: service_healthy
networks:
- jobforge-network
restart: unless-stopped
frontend:
build:
context: .
dockerfile: Dockerfile.frontend
ports:
- "8501:8501"
# PostgreSQL with pgvector
postgres:
image: pgvector/pgvector:pg16
container_name: jobforge-postgres
environment:
- BACKEND_URL=http://backend:8000
- POSTGRES_DB=jobforge
- POSTGRES_USER=jobforge
- POSTGRES_PASSWORD=${DB_PASSWORD}
volumes:
- ./src/frontend:/app/src/frontend
- postgres_data:/var/lib/postgresql/data
- ./backups:/backups
networks:
- jobforge-network
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U jobforge -d jobforge"]
interval: 10s
timeout: 5s
retries: 5
# Nginx Reverse Proxy
nginx:
image: nginx:alpine
container_name: jobforge-nginx
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
- ./ssl:/etc/nginx/ssl:ro
depends_on:
- backend
command: python src/frontend/main.py
- jobforge-app
networks:
- jobforge-network
restart: unless-stopped
networks:
jobforge-network:
driver: bridge
volumes:
postgres_data:
driver: local
```
---
## 📁 MVP Project Structure
## 📁 Web Application Project Structure
```
jobforge-mvp/
job-forge/
├── docker-compose.yml
├── Dockerfile.backend
├── Dockerfile.frontend
├── requirements-backend.txt
├── requirements-frontend.txt
├── Dockerfile
├── requirements.txt
├── requirements-dev.txt
├── .env.example
├── database/
│ └── init.sql
├── src/
│ ├── backend/
│ │ ├── main.py
│ │ ├── api/
│ │ │ ├── auth.py
│ │ │ ├── applications.py
│ │ │ ├── documents.py
│ │ │ └── processing.py
│ │ ├── services/
│ │ │ ├── auth_service.py
│ │ │ ├── application_service.py
│ │ │ ├── document_service.py
│ │ │ └── ai_orchestrator.py
│ │ ├── database/
│ │ │ ├── connection.py
│ │ │ └── models.py
│ │ └── models/
│ │ ├── requests.py
│ │ └── responses.py
│ ├── frontend/
│ │ ├── main.py
│ │ ├── components/
│ │ │ ├── sidebar.py
│ │ │ ├── topbar.py
│ │ │ └── editor.py
│ │ ├── pages/
│ │ │ ├── login.py
│ │ │ ├── dashboard.py
│ │ │ └── application.py
│ │ └── api_client/
│ │ └── client.py
│ ├── agents/
│ │ ├── research_agent.py
│ │ ├── resume_optimizer.py
│ │ ├── cover_letter_generator.py
│ │ └── claude_client.py
│ └── helpers/
│ ├── validators.py
│ └── formatters.py
└── user_data/
└── resumes/
├── pytest.ini
├── alembic.ini
├── CLAUDE.md
├── README.md
├── app/
│ ├── main.py # FastAPI + Dash application entry
│ ├── core/
│ │ ├── config.py # Application configuration
│ │ ├── database.py # Database connection and session
│ │ ├── security.py # JWT authentication utilities
│ │ └── exceptions.py # Custom exception handlers
│ ├── api/
│ │ ├── v1/
│ │ │ ├── auth.py # Authentication endpoints
│ │ │ ├── applications.py # Application CRUD endpoints
│ │ │ └── documents.py # Document management endpoints
│ │ └── dependencies.py # FastAPI dependencies
│ ├── models/
│ │ ├── user.py # User SQLAlchemy model
│ │ ├── application.py # Application SQLAlchemy model
│ │ └── document.py # Document SQLAlchemy model
│ ├── schemas/
│ │ ├── user.py # User Pydantic schemas
│ │ ├── application.py # Application Pydantic schemas
│ │ └── auth.py # Authentication schemas
│ ├── crud/
│ │ ├── user.py # User database operations
│ │ ├── application.py # Application database operations
│ │ └── document.py # Document database operations
│ ├── services/
│ │ ├── auth.py # Authentication service
│ │ ├── application.py # Application business logic
│ │ └── ai/
│ │ ├── claude_service.py # Claude API integration
│ │ ├── openai_service.py # OpenAI API integration
│ │ └── document_generator.py # AI document generation
│ └── frontend/
│ ├── app.py # Dash application setup
│ ├── layouts/
│ │ ├── dashboard.py # Main dashboard layout
│ │ ├── auth.py # Login/register layouts
│ │ └── application.py # Application detail layout
│ ├── components/
│ │ ├── navigation.py # Navigation components
│ │ ├── forms.py # Form components
│ │ └── modals.py # Modal components
│ └── callbacks/
│ ├── auth.py # Authentication callbacks
│ ├── application.py # Application callbacks
│ └── navigation.py # Navigation callbacks
├── alembic/
│ ├── versions/ # Database migration files
│ └── env.py # Alembic configuration
├── tests/
│ ├── conftest.py # Pytest configuration and fixtures
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # End-to-end tests
├── docs/
│ ├── README.md # Main documentation hub
│ ├── development/ # Development documentation
│ ├── infrastructure/ # Deployment documentation
│ └── testing/ # Testing documentation
├── nginx/
│ └── nginx.conf # Nginx configuration
├── logs/ # Application logs
├── uploads/ # File uploads
└── backups/ # Database backups
```
---
*This MVP architecture focuses on delivering the core job application workflow with essential features. It establishes the foundation for Phase 2 development while providing immediate value for personal job application management and concept validation.*
*This web application architecture provides a comprehensive, production-ready solution for AI-powered job application management. The FastAPI backend with Dash frontend delivers a modern web experience while maintaining scalability and security for prototype development and future enhancements.*