> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinfindu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get FindU running locally in under 5 minutes

# Quick Start Guide

Get your FindU development environment set up and make your first contribution.

## Prerequisites

Before you begin, ensure you have:

<CardGroup cols={2}>
  <Card title="Required Tools" icon="wrench">
    * Git (v2.30+)
    * Node.js (v18+ LTS)
    * Python 3.8+
    * Xcode (for iOS development)
  </Card>

  <Card title="Optional Tools" icon="toolbox">
    * Docker Desktop (for local Supabase)
    * Supabase CLI (alternative to dashboard)
    * Railway CLI (for deployments)
  </Card>
</CardGroup>

<CardGroup cols={1}>
  <Card title="Access Needed" icon="key">
    * GitHub organization access
    * Supabase dashboard access
    * Slack workspace invite
  </Card>
</CardGroup>

### Installing Prerequisites

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    # Install Homebrew if needed
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    # Install required tools
    brew install git node python3

    # Optional tools
    brew install supabase/tap/supabase  # If you prefer CLI over dashboard
    brew install --cask docker           # For local Supabase

    # For iOS development
    # Install Xcode from App Store
    ```
  </Tab>

  <Tab title="Windows">
    ```bash theme={null}
    # Install using Chocolatey or download installers:
    choco install git nodejs python3

    # Optional tools
    scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
    scoop install supabase
    ```
  </Tab>
</Tabs>

<Note>
  Don't have access yet? See our [onboarding checklist](/developer/onboarding) for new team members.
</Note>

## Setting Up Your Workspace

Create a workspace directory and clone the repositories you need:

```bash theme={null}
# Create workspace
mkdir ~/findu && cd ~/findu

# Clone core repositories
git clone https://github.com/findu-app/ios_app.git
git clone https://github.com/findu-app/web_app.git
git clone https://github.com/findu-app/matching-algorithm.git
git clone https://github.com/findu-app/data_scraping.git
git clone https://github.com/findu-app/docs.git
```

<Note>
  Each repository has its own README with specific setup instructions. Total setup time is approximately 15-20 minutes including dependency installation.
</Note>

## Setting Up Each Repository

<Steps>
  <Step title="Switch to dev branch">
    Each repository uses a dev/main branch workflow. After cloning:

    ```bash theme={null}
    cd ios_app && git checkout dev && git pull origin dev
    cd ../web_app && git checkout dev && git pull origin dev
    cd ../matching-algorithm && git checkout dev && git pull origin dev
    cd ../data_scraping && git checkout dev && git pull origin dev
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    # Web app
    cd web_app && npm install

    # iOS app
    cd ../ios_app && pod install

    # ML engine
    cd ../matching-algorithm
    python -m venv venv
    source venv/bin/activate
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Configure Environment">
    Create environment files in each repository. Get credentials from your team lead:

    **Web App** (`web_app/.env`):

    ```bash theme={null}
    VITE_SUPABASE_URL=your_supabase_url
    VITE_SUPABASE_ANON_KEY=your_anon_key
    VITE_ENV=development
    ```

    **iOS App** (`ios_app/Secrets.xcconfig`):

    ```
    SUPABASE_URL = your_supabase_url
    SUPABASE_ANON_KEY = your_anon_key
    ```

    **Matching Algorithm** (`matching-algorithm/.env`):

    ```bash theme={null}
    SUPABASE_URL=your_supabase_url
    SUPABASE_KEY=your_anon_key
    ```
  </Step>
</Steps>

## Verify Your Setup

Run these commands to verify everything is working:

```bash theme={null}
# Check if all repositories were cloned
ls -la ~/findu
# Should show: ios_app, web_app, matching-algorithm, data_scraping, docs

# Verify you're on dev branch in each repo
cd ~/findu/web_app && git branch --show-current
# Should show: dev

# Test web app
npm run dev
# Should start development server on http://localhost:5173

# Test matching algorithm
cd ../matching-algorithm
source venv/bin/activate  # or venv\Scripts\activate on Windows
python main.py
# Should start API on http://localhost:8000
```

<Accordion title="Troubleshooting Common Issues">
  * **"Branch 'dev' not found"**: The dev branch might not exist yet. Use `main` or create dev from main
  * **"npm: command not found"**: Install Node.js or check PATH
  * **"Cannot find module"**: Run `npm install` in the project directory
  * **"Python version error"**: Use Python 3.9-3.11 (3.13 has compatibility issues)
  * **"Supabase connection error"**: Verify your credentials in .env files
</Accordion>

## Make Your First Change

<Steps>
  <Step title="Switch to dev branch">
    ```bash theme={null}
    cd ~/findu/web_app
    git checkout dev
    git pull origin dev
    ```
  </Step>

  <Step title="Create feature branch">
    ```bash theme={null}
    git checkout -b feature/your-name-first-pr
    ```
  </Step>

  <Step title="Make a small change">
    Edit any file (try updating a comment or fixing a typo)

    Then test your change:

    * Build and run locally
    * Click around to make sure nothing broke
    * Check the browser console for errors
  </Step>

  <Step title="Commit and push">
    ```bash theme={null}
    git add .
    git commit -m "My first FindU commit"
    git push -u origin feature/your-name-first-pr
    ```
  </Step>

  <Step title="Open PR">
    Go to GitHub and create a pull request:

    * **Base branch**: `dev` (NOT main!)
    * **Compare branch**: your feature branch
    * Follow the PR template
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Understand the Architecture" icon="sitemap" href="/architecture">
    Learn how all the pieces fit together
  </Card>

  <Card title="Development Workflow" icon="code-branch" href="/developer/workflow-guide">
    Master our git workflow and best practices
  </Card>

  <Card title="Find an Issue" icon="bug" href="/contributing">
    Browse good first issues to work on
  </Card>

  <Card title="Join Slack" icon="slack" href="https://findu-team.slack.com/archives/dev">
    Connect with the team for help
  </Card>
</CardGroup>

<Warning>
  Always create branches from `dev`, not `main`! Our main branch is protected and only receives updates from dev.
</Warning>