QUICK_START.md

Quick Start Guide - Modern React SaaS

Complete setup and run instructions for the new Job Apply AI React frontend.

📋 What's New

✨ Modern React 18 Frontend

• Beautiful dark SaaS theme (black + emerald green)
• Smooth Framer Motion animations
• Professional component library
• Responsive design for all devices

🔄 Improved State Management

• Zustand for reactive state
• Persistent storage
• Clean API

⚡ Better Performance

• Optimized React build
• Code splitting
• CSS-in-JS with Tailwind

🛠️ REST API Endpoints

• Proper API structure
• CORS enabled
• Easy to extend

🚀 Quick Start (5 minutes)

1️⃣ Install Dependencies

# Python backend
pip install -r requirements.txt
pip install flask-cors

# React frontend
cd frontend
npm install

2️⃣ Start the Backend (Terminal 1)

# Activate virtual environment
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate.bat  # Windows

# Run Flask server
python -m job_apply_ai.ui.app_new

You should see:

Running on http://0.0.0.0:5050

3️⃣ Start the Frontend (Terminal 2)

cd frontend
npm run dev

You should see:

VITE v5.0.0 ready in 123 ms
➜  Local:   http://localhost:3000/

4️⃣ Open Your Browser

Visit: http://localhost:3000

You should see the beautiful Job Apply AI home page! 🎉

📖 How to Use

Home Page

• Overview of features
• Call-to-action buttons
• Statistics

Workflow

1. Upload CV - Drag and drop your .docx file
2. Search Jobs - Enter job title and location
3. Review Jobs - See matched skills for each job
4. Generate CVs - Select jobs and create tailored CVs
5. Download - Get all CVs as a ZIP file

Settings

• Toggle between "Smart Mode" (local) and "AI Mode" (with API)
• Configure LLM provider
• Enable/disable professional summaries

🎨 Customization

Change Theme Colors

Edit frontend/tailwind.config.js:

colors: {
  emerald: {
    500: '#22c55e',  // Change to your color
    // ... other shades
  },
  black: '#0A0E27',  // Or your dark color
  // Custom colors here
}

Modify Animations

Edit frontend/src/components/common/Button.tsx:

whileHover={{ y: -2 }}  // Change hover distance
whileTap={{ scale: 0.98 }}  // Change tap scale
transition={{ duration: 0.3 }}  // Change duration

Add New Pages

1. Create frontend/src/components/pages/NewPage.tsx
2. Import in frontend/src/App.tsx
3. Add route logic in App component

Example:

{currentPage === 'newpage' && (
  <NewPage onBack={() => setCurrentPage('home')} />
)}

🔧 Development Commands

# Frontend
cd frontend

npm run dev        # Start dev server
npm run build      # Build for production
npm run preview    # Preview production build
npm run type-check # Check TypeScript
npm run lint       # Run ESLint

📁 Project Structure

Job-apply-AI/
├── frontend/                    # React app (NEW)
│   ├── src/
│   │   ├── components/
│   │   │   ├── common/         # Reusable components
│   │   │   ├── pages/          # Full pages
│   │   │   └── sections/       # Page sections
│   │   ├── store/              # Zustand store
│   │   ├── types/              # TypeScript types
│   │   ├── utils/
│   │   │   ├── api.ts          # API calls
│   │   │   └── helpers.ts      # Utilities
│   │   ├── styles/             # Global CSS
│   │   ├── App.tsx             # Root component
│   │   └── main.tsx            # Entry point
│   ├── tailwind.config.js      # Theme config
│   ├── vite.config.ts          # Build config
│   └── package.json
│
├── job_apply_ai/               # Python backend
│   ├── ui/
│   │   ├── app_new.py          # New Flask app (UPDATED)
│   │   └── app.py              # Old Flask app (legacy)
│   ├── scraper/                # Job scraping
│   ├── cv_modifier/            # CV customization
│   └── utils/                  # Helpers
│
├── requirements.txt            # Python deps (UPDATED)
├── DEPLOYMENT_GUIDE.md         # Deployment (NEW)
├── SAAS_FEATURES.md            # Features doc (NEW)
└── README.md                   # Main docs (UPDATED)

🚀 Deploying to Production

Build the frontend

cd frontend
npm run build

This creates frontend/dist/ with optimized files that Flask will serve.

Run with production settings

# Set environment variables
export FLASK_ENV=production
export FLASK_DEBUG=False
export SECRET_KEY=your_random_secret_key

# Run with gunicorn
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5050 job_apply_ai.ui.app:app

Visit http://localhost:5050 to see the production build.

🐛 Troubleshooting

Frontend won't load

# Make sure backend is running
curl http://localhost:5050

# Check React dev server
# Should see "Ready in XXX ms" in terminal

API calls failing

# Check if endpoints exist
curl http://localhost:5050/api/health

# Should return: {"status":"ok","version":"2.0.0"}

Styles look wrong

# Restart dev server
npm run dev

# Clear cache
rm -rf node_modules/.vite

Port already in use

# Change port in vite.config.ts or terminal
npm run dev -- --port 3001

# Or change Flask port
export PORT=5051
python -m job_apply_ai.ui.app_new

📚 Key Files to Know

Frontend

• App.tsx - Main app logic, page routing
• appStore.ts - All state management
• api.ts - Backend API calls
• tailwind.config.js - Colors, themes, animations
• Job components - Job search, listing, generation

Backend

• app_new.py - Flask server with React routing + APIs
• linkedin.py - Job scraping
• cv_analyzer.py - Skill extraction
• cv_modifier.py - CV customization

🎯 Common Tasks

Add a new API endpoint

1. Add backend method in app_new.py:

@app.route('/api/my-endpoint', methods=['POST'])
def my_endpoint():
    return jsonify({'success': True})

2. Add frontend call in api.ts:

async myAPICall() {
  const response = await api.post('/my-endpoint');
  return response.data;
}

3. Use in component:

const handleClick = async () => {
  const data = await jobsAPI.myAPICall();
  setNotification({ type: 'success', message: 'Done!' });
}

Change color scheme

All colors are in tailwind.config.js and globals.css. Change:

• emerald colors for primary actions
• slate colors for text/backgrounds
• black for dark mode

Add a loading skeleton

Import Spinner:

import { Spinner } from '@/components/common';

<Spinner size="md" />  // sm, md, lg

Create a modal dialog

import Modal from '@/components/common/Modal';

<Modal isOpen={isOpen} onClose={onClose} title="Confirm">
  Your content here
</Modal>

🌐 Environment Variables

Backend (.env)

FLASK_ENV=development
CV_TAILORING_MODE=local
LLM_PROVIDER=groq
GROQ_API_KEY=xxxxx

Frontend (.env in frontend/)

VITE_API_URL=http://localhost:5050
VITE_APP_NAME=Job Apply AI

📞 Support

Need help?

1. Check logs - Terminal output usually shows the issue
2. Read DEPLOYMENT_GUIDE.md - Detailed deployment info
3. Review SAAS_FEATURES.md - Feature documentation
4. Check frontend/README.md - React-specific docs

✅ Checklist

• Installed Python and Node.js 18+
• Ran npm install in frontend folder
• Pinned flask-cors in requirements.txt
• Started backend on port 5050
• Started frontend on port 3000
• Opened http://localhost:3000
• Tested file upload
• Tested job search
• Tested CV generation
• ☀️ Celebrated the beautiful new UI!

---

Ready to use your amazing new Job Apply AI? 🎉

Start building better job applications! 💼✨