Skip to main content

​
FindU Development Guide

This guide covers our development workflow, standards, and best practices for the FindU engineering team.

​
Repository Overview

web_app

React dashboard for partners
  • Partner analytics
  • Messaging interface
  • Profile management
  • Scholarship tools

ios_app

Native iOS app for students
  • College swiping
  • Student messaging
  • Profile creation
  • Social features

matching-algorithm

ML matching engine
  • Recommendation API
  • Learning algorithms
  • Performance optimization
  • Mobile endpoints

data_scraping

Data collection & enrichment
  • College data updates
  • Image scraping
  • AI-powered enhancements
  • Automated pipelines

​
Development Process

​
1. Starting New Work

1

Check Current Sprint

  • Review sprint board for assigned tasks
  • Check with team lead for priorities
  • Understand acceptance criteria
2

Pull Latest Changes

Always start from updated dev branch:
git checkout dev
git pull origin dev
3

Create Feature Branch

Use descriptive branch names:
git checkout -b feature/add-scholarship-filters
git checkout -b fix/profile-creation-bug
git checkout -b chore/update-dependencies

​
2. Making Changes

Always follow our branch strategy:
Never branch from or PR to main directly. Always use dev as your base. The main branch is protected and only receives updates from dev.

​
Branch Protection Rules

Main Branch:
  • Requires PR from dev branch only
  • Requires passing CI/CD checks
  • No direct commits allowed
  • Auto-deploys to production
Dev Branch:
  • Requires PR from feature branches
  • No approval required (trust-based)
  • Direct commits allowed for hotfixes
  • Auto-deploys to development environment
Feature Branches:
  • No protection rules
  • Should be deleted after merge
  • Always created from dev

​
3. Code Standards

  • TypeScript/React
  • Swift/iOS
  • Python
// Good: Clear naming, proper types
interface StudentProfile {
  id: string;
  name: string;
  graduationYear: number;
}

// Good: Descriptive function names
export function calculateMatchScore(
  student: StudentProfile,
  school: School
): number {
  // Implementation
}

​
4. Testing

Before submitting your PR:
  • Run existing tests
  • Add tests for new functionality
  • Test manually in the app
  • Check for console errors
  • Verify mobile responsiveness (if web)

​
5. Pull Request

Use our simplified PR template: 
## What does this PR do?
[Brief description]

## Type of change
- Bug fix / New feature / Improvement

## How did you test this?
- [ ] I tested this locally
- [ ] Specific things I tested: [list them]

## Screenshots (if UI changes)
[Add screenshots]

​
Review Process

What happens after you open a PR:
1

Automated Checks

GitHub Actions will run:
  • Linting
  • Type checking
  • Security checks
  • Build verification
2

Code Review

Team members will review:
  • Code quality and standards
  • Architecture alignment
  • Performance impact
  • Security considerations
3

Testing

  • Verify changes work locally
  • Test on dev environment
  • Check for regressions
  • Mobile app: test on devices
4

Merge & Deploy

Once approved:
  • PR merged to dev
  • Auto-deployed to dev environment
  • Monitor for issues
  • Plan production release

​
Team Communication

Daily Standup

Share progress and blockers
  • What you completed
  • What you’re working on
  • Any blockers

Technical Help

Getting unstuck:
  • Ask in #dev-help
  • Pair with teammates
  • Schedule 1:1 with lead

Design Decisions

For architecture questions:
  • Document in PR
  • Discuss in tech meeting
  • Create ADR if needed

Sprint Planning

Weekly planning:
  • Review upcoming work
  • Estimate tasks
  • Identify dependencies

​
Development Standards

​
Code Quality

  • Write clean, readable code
  • Add meaningful comments for complex logic
  • Keep functions small and focused
  • Follow DRY principles

​
Testing

  • Write tests for new features
  • Maintain existing test coverage
  • Test edge cases
  • Manual testing before PR

​
Documentation

  • Update README for significant changes
  • Document new APIs
  • Keep CLAUDE.md files current
  • Add inline documentation

​
Security

  • Never commit secrets
  • Follow security best practices
  • Review dependencies
  • Report vulnerabilities immediately

​
Deployment Process

​
Automated Deployment Pipeline

​
Environment Details

1

Development Environment

Branch: dev
  • Auto-deploys on merge via Railway
  • Development Supabase instance
  • Testing ground for new features
  • No approval required for deployment
  • URL: *-dev.railway.app
2

Production Environment

Branch: main
  • Auto-deploys on merge via Railway
  • Production Supabase instance (50k+ users)
  • Live user traffic
  • Requires PR review from dev branch
  • URLs: findu.app, *.railway.app
3

Deployment Checklist

Before merging dev → main:
  • All CI/CD checks passing
  • Tested on dev environment
  • Database migrations reviewed
  • No critical bugs in dev
  • Performance metrics acceptable
  • iOS app version bumped (if applicable)
Remember: We’re building something amazing together. Quality over speed, communication over assumptions.