# 🚀 VIBN Local Development Setup

Complete guide to running VIBN locally on your machine.

## ✅ Prerequisites

- **Node.js** 18+ (check with `node --version`)
- **npm** or **pnpm** package manager
- **Firebase Project** (for authentication and database)
- **GitHub OAuth App** (optional, for GitHub integration)

---

## 📦 Step 1: Install Dependencies

```bash
cd vibn-frontend
npm install
```

---

## 🔐 Step 2: Environment Variables

Create a `.env.local` file in the `vibn-frontend` directory:

```bash
touch .env.local
```

### Required Environment Variables

Copy and paste the following into `.env.local` and replace with your actual values:

```env
# ===================================
# Firebase Client Config (Public)
# Get these from Firebase Console > Project Settings > General
# ===================================
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project_id.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_firebase_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-XXXXXXXXXX

# ===================================
# Firebase Admin Config (Server-side ONLY)
# Get these from Firebase Console > Project Settings > Service Accounts
# Click "Generate New Private Key" to download JSON file
# ===================================
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your_project_id.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour_Private_Key_Here\n-----END PRIVATE KEY-----\n"

# ===================================
# GitHub OAuth (Optional)
# Create an OAuth App at: https://github.com/settings/developers
# Authorization callback URL: http://localhost:3000/api/github/oauth/callback
# ===================================
NEXT_PUBLIC_GITHUB_CLIENT_ID=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
```

---

## 🔥 Step 3: Firebase Setup

### 3.1 Get Firebase Credentials

1. Go to [Firebase Console](https://console.firebase.google.com/)
2. Select your project (or create a new one)
3. Navigate to **Project Settings** (⚙️ icon)

#### Client Config (Public):
- Under **General** tab, scroll to "Your apps"
- Copy the `firebaseConfig` values
- These go in `NEXT_PUBLIC_FIREBASE_*` variables

#### Admin Config (Private):
- Go to **Service Accounts** tab
- Click **Generate New Private Key**
- Download the JSON file
- Extract values:
  - `FIREBASE_PROJECT_ID` = `project_id` from JSON
  - `FIREBASE_CLIENT_EMAIL` = `client_email` from JSON
  - `FIREBASE_PRIVATE_KEY` = `private_key` from JSON (keep the `\n` characters!)

### 3.2 Enable Authentication

1. In Firebase Console, go to **Authentication** → **Sign-in method**
2. Enable **Email/Password**
3. Enable **Google** (optional)

### 3.3 Setup Firestore

1. In Firebase Console, go to **Firestore Database**
2. Click **Create database**
3. Choose **Start in production mode** (we have custom rules)
4. Select a location (closest to your users)

### 3.4 Deploy Firestore Rules & Indexes

```bash
# Deploy security rules
npm run firebase:deploy:rules

# Deploy indexes
npm run firebase:deploy:indexes
```

---

## 🐙 Step 4: GitHub OAuth Setup (Optional)

Only needed if you want to test GitHub repository integration.

1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Click **New OAuth App**
3. Fill in:
   - **Application name**: VIBN Local
   - **Homepage URL**: `http://localhost:3000`
   - **Authorization callback URL**: `http://localhost:3000/api/github/oauth/callback`
4. Copy **Client ID** → `NEXT_PUBLIC_GITHUB_CLIENT_ID`
5. Generate **Client Secret** → `GITHUB_CLIENT_SECRET`

---

## 🏃 Step 5: Run the Development Server

```bash
npm run dev
```

The app will be available at **http://localhost:3000**

### First Time Setup

1. **Create an account**: Click "Get Started" or go to `/auth`
2. **Sign up** with email/password or Google
3. **Create your first project**: Click "New Project"
4. **Start coding**: Open your project in Cursor and install the monitor extension

---

## 📂 Development Scripts

```bash
# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Lint code
npm run lint

# Deploy Firebase rules
npm run firebase:deploy:rules

# Deploy Firebase indexes
npm run firebase:deploy:indexes

# Run Firebase emulators (test without production database)
npm run firebase:emulators
```

---

## 🛠️ Troubleshooting

### Firebase Admin "Credentials not configured"

**Problem**: API routes throw errors about Firebase Admin not being initialized.

**Solution**: Make sure your `.env.local` has all three `FIREBASE_*` variables (not `NEXT_PUBLIC_`):
- `FIREBASE_PROJECT_ID`
- `FIREBASE_CLIENT_EMAIL`
- `FIREBASE_PRIVATE_KEY`

Make sure the private key includes `\n` for newlines and is wrapped in quotes.

### "Failed to fetch" or CORS errors

**Problem**: Client can't connect to Firebase.

**Solution**: 
1. Check that all `NEXT_PUBLIC_FIREBASE_*` variables are set correctly
2. Make sure Firebase Authentication is enabled in the console
3. Check browser console for specific error messages

### Dev server won't start

**Problem**: Port 3000 is already in use.

**Solution**:
```bash
# Find what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3001 npm run dev
```

### Changes not showing up

**Problem**: You made code changes but they're not reflected in the browser.

**Solution**:
1. Hard refresh: `Cmd+Shift+R` (Mac) or `Ctrl+Shift+R` (Windows)
2. Clear Next.js cache: `rm -rf .next`
3. Restart the dev server

---

## 📁 Project Structure

```
vibn-frontend/
├── app/                        # Next.js App Router
│   ├── (marketing)/           # Marketing site (public)
│   │   └── page.tsx           # Homepage
│   ├── [workspace]/           # Workspace pages (authenticated)
│   │   ├── projects/          # Projects list
│   │   ├── connections/       # API connections & keys
│   │   └── project/[id]/      # Individual project pages
│   ├── auth/                  # Authentication pages
│   ├── api/                   # API routes
│   │   ├── sessions/          # Session tracking
│   │   ├── projects/          # Project management
│   │   ├── github/            # GitHub OAuth
│   │   └── stats/             # Analytics
│   └── layout.tsx             # Root layout
├── components/                 # React components
│   ├── layout/                # Layout components (left rail, sidebar, etc)
│   ├── ui/                    # shadcn/ui components
│   └── *.tsx                  # Feature components
├── lib/                       # Utility libraries
│   ├── firebase/              # Firebase config & admin
│   ├── github/                # GitHub OAuth
│   └── utils.ts               # Helper functions
├── marketing/                 # Marketing content & components
│   ├── components/            # Marketing-specific components
│   └── content/               # Marketing copy
├── public/                    # Static assets
├── firestore.rules            # Firestore security rules
├── firestore.indexes.json     # Firestore indexes
└── .env.local                 # Environment variables (YOU CREATE THIS)
```

---

## 🌐 Production Deployment

This project is configured for **Vercel** deployment:

1. Push to GitHub
2. Connect your repo to [Vercel](https://vercel.com)
3. Add all environment variables in Vercel dashboard
4. Deploy automatically on push to `main`

Firebase Hosting is also configured but Vercel is recommended for Next.js.

---

## ✨ VS Code Tips

### Recommended Extensions

- **ESLint** - Code linting
- **Tailwind CSS IntelliSense** - Tailwind autocomplete
- **Prettier** - Code formatting
- **Firebase** - Firebase syntax highlighting

### Settings

Add to `.vscode/settings.json`:

```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "tailwindCSS.experimental.classRegex": [
    ["cn\\(([^)]*)\\)", "'([^']*)'"]
  ]
}
```

---

## 📖 Additional Resources

- [Next.js Documentation](https://nextjs.org/docs)
- [Firebase Documentation](https://firebase.google.com/docs)
- [Tailwind CSS](https://tailwindcss.com/docs)
- [shadcn/ui](https://ui.shadcn.com/)
- [Lucide Icons](https://lucide.dev/)

---

## 💬 Need Help?

- Check the [Project Instructions](../PROJECT_INSTRUCTIONS.md)
- Review the [Firebase Admin Setup](lib/firebase/admin.ts)
- Look at existing [API routes](app/api/) for examples

---

**Status**: ✅ Ready for local development
**Last Updated**: November 2025