# JobyApp

> AI-Powered Job Search & Application Automation Platform that combines intelligent job scraping from multiple sources, AI-powered job-candidate matching, and automated generation of personalized application documents.

JobyApp is a comprehensive platform that streamlines the entire job hunting process through intelligent automation, multi-platform job discovery, AI-powered candidate matching, and personalized document generation. The platform features a modern multi-service architecture with separate frontend, backend, and Python processing pipelines.

## Core Technology Stack

**Frontend**: Astro 5.12.0 with React 18.2.0 islands, TypeScript, Tailwind CSS, deployed on Vercel
**Backend**: Node.js 18+ with Express 5.1.0, Sequelize ORM, PostgreSQL, Redis cache, deployed on Heroku  
**Python Pipeline**: Python 3.8+ with OpenAI integration, job scraping via JobSpy, document processing with python-docx
**Key Services**: Authentication (JWT + OAuth), File processing, Background workers, WebSocket real-time updates

## API Endpoints & Services

### Authentication System
- **POST /api/auth/register** - User registration with email validation
- **POST /api/auth/login** - JWT-based user authentication  
- **POST /api/auth/google** - Google OAuth 2.0 integration
- **POST /api/auth/logout** - Secure session termination
- **GET /api/auth/status** - Authentication status check
- **Implementation**: Passport.js with bcrypt password hashing, secure cookie management

### Job Search & Discovery
- **POST /api/jobs/search** - Multi-platform job search with advanced filters
- **POST /api/jobs/save** - Save interesting job opportunities
- **GET /api/jobs/saved** - Retrieve saved job listings
- **DELETE /api/jobs/saved/:id** - Remove saved jobs
- **Platforms**: LinkedIn, Indeed, Welcome to the Jungle, HelloWork, France Travail, Glassdoor
- **Filters**: Location, contract type, remote work, salary range, experience level, job freshness

### Document Generation
- **POST /api/generation/runs** - Create new document generation run
- **GET /api/generation/runs** - List user generation history
- **GET /api/generation/runs/:id** - Get detailed run information
- **POST /api/generation/export** - Export documents as ZIP packages
- **PATCH /api/generation/runs/:id/config** - Update generation configuration
- **DELETE /api/generation/runs/:id** - Delete generation runs
- **Features**: Template-based DOCX generation, smart tag replacement, batch processing

### Template Management
- **GET /api/templates** - List user document templates
- **POST /api/templates/upload** - Upload new DOCX templates
- **GET /api/templates/:id** - Retrieve specific template details
- **DELETE /api/templates/:id** - Remove templates
- **Capabilities**: Template versioning, preview generation, tag validation

### Profile Management
- **GET /api/profile** - Retrieve user profile data
- **POST /api/profile** - Create or update profile information
- **GET /api/profile/analyze** - AI-powered profile completeness analysis
- **Components**: Personal information, experience, education, skills, projects

## System Architecture

### Frontend Architecture (square-spiral)
- **Framework**: Astro static site generation with React islands for interactivity
- **Routing**: File-based routing with dynamic routes for job details and user dashboards
- **State Management**: React hooks and Context API for local state, API integration for server state
- **Components**: Modular component library with dashboard, templates, interview preparation, and profile management
- **Multi-language**: Complete French/English localization with i18n support
- **Performance**: Static optimization, lazy loading, CDN deployment via Vercel

### Backend Architecture (jobyapp-server)
- **Framework**: Express.js with middleware for authentication, rate limiting, security, and logging
- **Database**: PostgreSQL with Sequelize ORM, comprehensive migrations, and relationship modeling
- **Caching**: Redis for session management, API response caching, and rate limiting
- **Authentication**: JWT tokens with refresh mechanism, Google OAuth integration, secure cookie handling
- **File Processing**: Multer for uploads, docx manipulation, template-based document generation
- **Background Jobs**: Bull queue system for async processing, Python script integration, error handling

### Python Processing Pipeline
- **Job Scraping**: Custom JobSpy integration for multi-platform job data extraction
- **AI Integration**: OpenAI GPT models for job-candidate matching and content generation
- **Document Processing**: python-docx for template manipulation, tag replacement, formatting preservation
- **Data Processing**: Pandas for data transformation, cleanup, and analysis
- **Performance**: Multi-threading for scraping, batch processing, error recovery

## Database Schema

### Core Models
- **User**: Authentication, profile data, subscription management
- **JobOffer**: Scraped job data, source tracking, metadata
- **Template**: User document templates, version control
- **Run**: Document generation sessions, configuration, results
- **RunResult**: Generated documents, file paths, metadata
- **Subscription**: Payment processing, feature access, quota management
- **Profile**: Extended user profiles, skills, experience, education

### Relationships
- Users → Templates (one-to-many)
- Users → Runs (one-to-many) 
- Runs → RunResults (one-to-many)
- Users → Subscriptions (one-to-one)
- Users → Profiles (one-to-one)

## Development Workflow

### Local Development Setup
```bash
# Backend setup
cd jobyapp-server
npm install
pip install -r requirements.txt
cp .env.example .env
npm run db:migrate

# Frontend setup  
cd ../square-spiral
npm install
cp .env.example .env

# Run services
npm run dev  # Backend (port 5000)
npm run dev  # Frontend (port 4321)
redis-server  # Optional caching
```

### Testing Framework
- **E2E Testing**: Playwright with comprehensive user flow coverage
- **API Testing**: Jest for unit and integration tests
- **Database Testing**: Test containers with isolated test databases
- **Performance Testing**: K6 for load testing and performance benchmarks

### CI/CD Pipeline
- **GitHub Actions**: Automated testing, deployment, and quality checks
- **Backend Deployment**: Heroku with database migrations and environment management
- **Frontend Deployment**: Vercel with automatic previews and production builds
- **Security**: Automated security scanning, dependency updates, vulnerability checks

## Security Implementation

### Authentication & Authorization
- JWT tokens with secure signing and expiration
- Google OAuth 2.0 integration with proper scope management
- Session management with secure HttpOnly cookies
- Role-based access control for admin features
- Password hashing with bcrypt and salt rounds

### API Security
- Rate limiting with express-rate-limit and Redis
- CORS configuration for cross-origin requests
- Input validation and sanitization with custom validators
- SQL injection prevention via Sequelize ORM
- File upload security with type and size validation

### Data Protection
- Environment variable management for secrets
- Secure database connections with SSL
- Redis authentication and network isolation
- Logging security events and audit trails
- GDPR compliance with data deletion capabilities

## Performance Optimization

### Caching Strategy
- Redis-based API response caching with TTL
- Database query optimization with proper indexing
- Static asset optimization with CDN delivery
- Browser caching with appropriate headers
- Memory management for high-load operations

### Database Performance
- Connection pooling with Sequelize
- Query optimization and N+1 prevention
- Proper foreign key relationships
- Database migrations with rollback capability
- Backup and recovery procedures

### Frontend Performance
- Astro static site generation for optimal load times
- React islands for minimal JavaScript bundle
- Image optimization and lazy loading
- CSS purging with Tailwind
- Service worker implementation for offline capability

## Monitoring & Analytics

### Application Monitoring
- Custom performance monitoring middleware
- Database query performance tracking
- API response time monitoring
- Error tracking and alerting
- Resource usage monitoring

### Business Analytics
- User engagement tracking
- Job search success metrics
- Document generation statistics
- Subscription conversion tracking
- Feature usage analytics

### System Health
- Database connection monitoring
- Redis cache performance
- Python script execution tracking
- File system space monitoring
- External API integration status

## Documentation Structure

### Technical Documentation
- API endpoints with request/response examples
- Database schema documentation
- Component library with props and usage
- Deployment guides and environment setup
- Security implementation details

### User Documentation  
- Getting started guides
- Feature walkthroughs
- FAQ and troubleshooting
- Video tutorials and onboarding
- Best practices and tips

### Developer Resources
- Code contribution guidelines
- Development environment setup
- Testing procedures and standards
- Code style and formatting rules
- Architecture decision records

This comprehensive documentation provides AI assistants with complete understanding of JobyApp's architecture, capabilities, and implementation details for accurate code generation, integration guidance, and system analysis.