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)

Optional Tools

Docker Desktop (for local Supabase)
Supabase CLI (alternative to dashboard)
Railway CLI (for deployments)

Access Needed

GitHub organization access
Supabase dashboard access
Slack workspace invite

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

# 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

# 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

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

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

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

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

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

Make Your First Change

Switch to dev branch

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

Create feature branch

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

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

Commit and push

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

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.

Getting Started

Developer Guide

Web App

iOS App

Matching Algorithm

Database

AI Development

Quick Start

Quick Start Guide

Prerequisites

Required Tools

Optional Tools

Access Needed

Installing Prerequisites

Setting Up Your Workspace

Setting Up Each Repository

Verify Your Setup

Make Your First Change

Next Steps

Understand the Architecture

Development Workflow

Find an Issue

Join Slack

​Quick Start Guide

​Prerequisites

Required Tools

Optional Tools

Access Needed

​Installing Prerequisites

​Setting Up Your Workspace

​Setting Up Each Repository

​Verify Your Setup

​Make Your First Change

​Next Steps

Understand the Architecture

Development Workflow

Find an Issue

Join Slack

Quick Start Guide

Prerequisites

Installing Prerequisites

Setting Up Your Workspace

Setting Up Each Repository

Verify Your Setup

Make Your First Change

Next Steps