Skip to main content

​
Quick Start Guide

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

​
Prerequisites

Before you begin, ensure you have:

Required Tools

  • Git (v2.30+)
  • Node.js (v18+ LTS)
  • Python 3.8+
  • Xcode (for iOS development)

Access Needed

  • GitHub organization access
  • Supabase dashboard access
  • Slack workspace invite
  • Railway access (optional)

​
Installing Prerequisites

  • macOS
  • Windows
# 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

# For iOS development
# Install Xcode from App Store
Don’t have access yet? See our onboarding checklist for new team members.

​
Setting Up Your Workspace

Create a workspace directory and clone the repositories you need: 
# 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
Each repository has its own README with specific setup instructions. Total setup time is approximately 15-20 minutes including dependency installation.

​
Setting Up Each Repository

1

Switch to dev branch

Each repository uses a dev/main branch workflow. After cloning:
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
2

Install Dependencies

# 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
3

Configure Environment

Create environment files in each repository. Get credentials from your team lead:Web App (web_app/.env):
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):
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_anon_key

​
Verify Your Setup

Run these commands to verify everything is working: 
# 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
  • “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

​
Make Your First Change

1

Switch to dev branch

cd ~/findu/web_app
git checkout dev
git pull origin dev
2

Create feature branch

git checkout -b feature/your-name-first-pr
3

Make a small change

Edit any file (try updating a comment or fixing a typo)
4

Commit and push

git add .
git commit -m "My first FindU commit"
git push -u origin feature/your-name-first-pr
5

Open PR

Go to GitHub and create a pull request:
  • Base branch: dev (NOT main!)
  • Compare branch: your feature branch
  • Follow the PR template

​
Next Steps

Understand the Architecture

Learn how all the pieces fit together

Development Workflow

Master our git workflow and best practices

Find an Issue

Browse good first issues to work on

Join Slack

Connect with the team for help
Always create branches from dev, not main! Our main branch is protected and only receives updates from dev.