SETUP_GUIDE.md

# Lin - Comprehensive Setup Guide

This guide provides step-by-step instructions for setting up the Lin application on different operating systems.

## 📋 Table of Contents

1. [Prerequisites](#prerequisites)
2. [Quick Setup](#quick-setup)
3. [Detailed Setup Process](#detailed-setup-process)
4. [Environment Configuration](#environment-configuration)
5. [Development Workflow](#development-workflow)
6. [Troubleshooting](#troubleshooting)
7. [Platform-Specific Instructions](#platform-specific-instructions)

## 🚀 Prerequisites

Before you begin, ensure you have the following installed:

### System Requirements
- **Operating System**: Windows 10/11, macOS 10.14+, or Linux (Ubuntu 18.04+)
- **RAM**: 4GB minimum, 8GB recommended
- **Storage**: 1GB free space
- **Internet Connection**: Required for downloading dependencies

### Software Requirements
- **Node.js**: v16.0.0 or higher
- **npm**: v8.0.0 or higher
- **Python**: v3.8.0 or higher
- **Git**: v2.0.0 or higher (for cloning the repository)

### Verification Commands

**Windows Command Prompt:**
```cmd
# Check Node.js
node --version

# Check npm
npm --version

# Check Python
python --version

# Check Git
git --version
```

**Windows PowerShell:**
```powershell
# Check Node.js
node --version

# Check npm
npm --version

# Check Python
python --version

# Check Git
git --version
```

**Linux/macOS:**
```bash
# Check Node.js
node --version

# Check npm
npm --version

# Check Python
python3 --version

# Check Git
git --version
```

## 🚀 Quick Setup

### Option 1: Automated Setup (Recommended)

```bash
# Clone the repository
git clone <repository-url>
cd Lin

# Run automated setup
npm run setup
```

### Option 2: Manual Setup

```bash
# Clone the repository
git clone <repository-url>
cd Lin

# Install dependencies
npm install

# Setup environment files
npm run setup:env

# Build the project
npm run build
```

## 🔧 Detailed Setup Process

### Step 1: Clone the Repository

```bash
# Clone using HTTPS
git clone https://github.com/your-username/lin.git

# Or clone using SSH
git clone git@github.com:your-username/lin.git

# Navigate to the project directory
cd lin
```

### Step 2: Install Dependencies

```bash
# Install root dependencies
npm install

# Install frontend dependencies
npm run install:frontend

# Install backend dependencies
npm run install:backend
```

### Step 3: Configure Environment Variables

#### Frontend Configuration

```bash
# Navigate to frontend directory
cd frontend

# Copy environment template
cp .env.example .env.local

# Edit the environment file
# Open .env.local in your preferred editor
```

**Frontend Environment Variables (.env.local):**
```env
# API Configuration
REACT_APP_API_URL=http://localhost:5000
REACT_APP_ENVIRONMENT=development

# Optional: Custom configuration
REACT_APP_APP_NAME=Lin
REACT_APP_APP_VERSION=1.0.0
```

#### Backend Configuration

```bash
# Navigate to backend directory
cd ../backend

# Copy environment template
cp .env.example .env

# Edit the environment file
# Open .env in your preferred editor
```

**Backend Environment Variables (.env):**
```env
# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_api_key

# LinkedIn OAuth Configuration
CLIENT_ID=your_linkedin_client_id
CLIENT_SECRET=your_linkedin_client_secret
REDIRECT_URL=http://localhost:5000/api/auth/callback

# AI/ML Configuration
HUGGING_KEY=your_huggingface_api_key

# Security Configuration
JWT_SECRET_KEY=your_jwt_secret_key
SECRET_KEY=your_flask_secret_key

# Application Configuration
DEBUG=True
SCHEDULER_ENABLED=True
PORT=5000
```

### Step 4: Build the Project

```bash
# Navigate back to root directory
cd ..

# Build frontend for production
npm run build
```

### Step 5: Verify Installation

```bash
# Run tests
npm test

# Check linting
npm run lint

# Verify build
npm run preview
```

## 🌐 Environment Configuration

### Development Environment

```bash
# Start development servers
npm run dev:all

# Or start individually
npm run dev:frontend  # Frontend: http://localhost:3000
npm run dev:backend   # Backend: http://localhost:5000
```

### Production Environment

```bash
# Build for production
npm run build:prod

# Start production servers
npm run start:prod
```

### Environment-Specific Configuration

#### Development
- Frontend runs on http://localhost:3000
- Backend API runs on http://localhost:5000
- Hot reload enabled
- Debug logging enabled

#### Production
- Frontend built to static files
- Backend runs with optimized settings
- Debug logging disabled
- Error handling optimized

## 🛠️ Development Workflow

### Daily Development

1. **Start the Development Environment**
   ```bash
   npm run dev:all
   ```

2. **Make Changes to Code**
   - Frontend changes are automatically hot-reloaded
   - Backend changes require restart

3. **Test Changes**
   ```bash
   # Run specific tests
   npm test

   # Run linting
   npm run lint

   # Fix linting issues
   npm run lint:fix
   ```

4. **Commit Changes**
   ```bash
   git add .
   git commit -m "Descriptive commit message"
   git push
   ```

### Building for Production

1. **Clean Previous Builds**
   ```bash
   npm run clean
   ```

2. **Build for Production**
   ```bash
   npm run build:prod
   ```

3. **Test Production Build**
   ```bash
   npm run preview
   ```

4. **Deploy**
   ```bash
   # Deploy to your preferred hosting platform
   npm run deploy
   ```

### Common Development Tasks

#### Adding New Dependencies

```bash
# Add frontend dependency
cd frontend
npm install package-name

# Add backend dependency
cd ../backend
pip install package-name
```

#### Updating Dependencies

```bash
# Update frontend dependencies
cd frontend
npm update

# Update backend dependencies
cd ../backend
pip install --upgrade package-name
```

#### Database Migrations

```bash
# Run database migrations
cd backend
flask db upgrade
```

## 🔍 Troubleshooting

### Common Issues and Solutions

#### 1. ENOENT Error: no such file or directory

**Problem**: Running npm commands from the wrong directory
**Solution**: Always run npm commands from the project root directory

```bash
# Verify you're in the correct directory
pwd  # Linux/macOS
cd   # Windows (shows current directory)

# List files to confirm package.json exists
ls package.json  # Linux/macOS
dir package.json  # Windows
```

#### 2. Port Already in Use

**Problem**: Port 3000 or 5000 is already occupied
**Solution**: Find and stop the process using the port

**Windows Command Prompt:**
```cmd
# Find process using port 3000
netstat -ano | findstr :3000

# Find process using port 5000
netstat -ano | findstr :5000

# Kill process (replace PID with actual process ID)
taskkill /F /PID <PID>
```

**Windows PowerShell:**
```powershell
# Find process using port 3000
netstat -ano | Select-String ":3000"

# Find process using port 5000
netstat -ano | Select-String ":5000"

# Kill process (replace PID with actual process ID)
Stop-Process -Id <PID> -Force
```

**Linux/macOS:**
```bash
# Find process using port 3000
lsof -i :3000

# Find process using port 5000
lsof -i :5000

# Kill process (replace PID with actual process ID)
kill -9 <PID>
```

#### 3. Python/Node.js Not Recognized

**Problem**: Command not found errors
**Solution**: Add Python and Node.js to system PATH

**Windows:**
1. Press `Win + R` and type `sysdm.cpl`
2. Go to "Advanced" tab > "Environment Variables"
3. Under "System variables", edit "Path"
4. Add paths to Python and Node.js installation directories
5. Restart your terminal

**Linux (Ubuntu/Debian):**
```bash
# Add to ~/.bashrc or ~/.zshrc
echo 'export PATH=$PATH:/path/to/python' >> ~/.bashrc
echo 'export PATH=$PATH:/path/to/node' >> ~/.bashrc
source ~/.bashrc
```

**macOS:**
```bash
# Add to ~/.zshrc or ~/.bash_profile
echo 'export PATH=$PATH:/path/to/python' >> ~/.zshrc
echo 'export PATH=$PATH:/path/to/node' >> ~/.zshrc
source ~/.zshrc
```

#### 4. Permission Denied Errors

**Problem**: Permission issues when installing dependencies
**Solution**: Run with proper permissions or use package managers

**Windows:**
```cmd
# Run as Administrator
# Or check file permissions
```

**Linux/macOS:**
```bash
# Fix permissions
chmod -R 755 node_modules
chmod -R 755 backend/venv
```

#### 5. Environment Variable Issues

**Problem**: Environment variables not loading
**Solution**: Verify file paths and permissions

**Windows Command Prompt:**
```cmd
# Check if environment files exist
if exist frontend\.env.local (
    echo Frontend environment file exists
) else (
    echo Frontend environment file missing
)

if exist backend\.env (
    echo Backend environment file exists
) else (
    echo Backend environment file missing
)
```

**Windows PowerShell:**
```powershell
# Check if environment files exist
if (Test-Path frontend\.env.local) {
    Write-Host "Frontend environment file exists" -ForegroundColor Green
} else {
    Write-Host "Frontend environment file missing" -ForegroundColor Red
}

if (Test-Path backend\.env) {
    Write-Host "Backend environment file exists" -ForegroundColor Green
} else {
    Write-Host "Backend environment file missing" -ForegroundColor Red
}
```

## 🖥️ Platform-Specific Instructions

### Windows Setup

#### Prerequisites Installation
1. **Download Node.js**: Visit https://nodejs.org and download the LTS version
2. **Download Python**: Visit https://python.org and download Python 3.8+
3. **Install Git**: Download from https://git-scm.com

#### Environment Setup
```cmd
# Command Prompt setup
copy frontend\.env.example frontend\.env.local
copy backend\.env.example backend\.env

# PowerShell setup
Copy-Item frontend\.env.example -Destination frontend\.env.local
Copy-Item backend\.env.example -Destination backend\.env
```

#### Development Commands
```cmd
# Install dependencies
npm install
npm run install:all:win

# Start development
npm run dev:all

# Build project
npm run build
```

### macOS Setup

#### Prerequisites Installation
```bash
# Install using Homebrew
brew install node
brew install python
brew install git

# Or download from official websites
```

#### Environment Setup
```bash
# Copy environment files
cp frontend/.env.example frontend/.env.local
cp backend/.env.example backend/.env

# Set permissions
chmod 600 frontend/.env.local
chmod 600 backend/.env
```

#### Development Commands
```bash
# Install dependencies
npm install
npm run install:all

# Start development
npm run dev:all

# Build project
npm run build
```

### Linux Setup

#### Prerequisites Installation
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm python3 python3-pip git

# CentOS/RHEL
sudo yum install nodejs npm python3 python3-pip git

# Arch Linux
sudo pacman -S nodejs npm python python-pip git
```

#### Environment Setup
```bash
# Copy environment files
cp frontend/.env.example frontend/.env.local
cp backend/.env.example backend/.env

# Set permissions
chmod 600 frontend/.env.local
chmod 600 backend/.env
```

#### Development Commands
```bash
# Install dependencies
npm install
npm run install:all

# Start development
npm run dev:all

# Build project
npm run build
```

## 📚 Additional Resources

- [API Documentation](./backend/README.md)
- [Frontend Development Guide](./frontend/README.md)
- [Windows Compatibility Guide](./test_windows_compatibility.md)
- [Troubleshooting Guide](./TROUBLESHOOTING.md)
- [Contributing Guidelines](./CONTRIBUTING.md)

## 🆘 Getting Help

If you encounter issues not covered in this guide:

1. Check the [Troubleshooting Guide](./TROUBLESHOOTING.md)
2. Search existing [GitHub Issues](https://github.com/your-username/lin/issues)
3. Create a new issue with:
   - Operating system and version
   - Node.js and Python versions
   - Error messages and stack traces
   - Steps to reproduce the issue

## 🎯 Next Steps

After completing the setup:

1. **Explore the Application**: Navigate to http://localhost:3000
2. **Read the Documentation**: Check the API documentation and user guides
3. **Join the Community**: Join our Discord server or mailing list
4. **Start Contributing**: Check out the contributing guidelines

Happy coding! 🚀