​

Developer Workflow Guide

​

Daily Development Flow

# Pull latest changes from dev branch
cd ~/findu/web_app && git checkout dev && git pull origin dev
cd ~/findu/ios_app && git checkout dev && git pull origin dev
cd ~/findu/matching-algorithm && git checkout dev && git pull origin dev
cd ~/findu/data_scraping && git checkout dev && git pull origin dev

# Update dependencies if needed
cd ~/findu/web_app && npm install
# Repeat for other repos as needed

# Create branch from dev (not main!)
git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name

# Run tests based on what you're working on
cd ~/findu/web_app && npm test
cd ~/findu/matching-algorithm && pytest tests/

# Run the development server
cd ~/findu/web_app && npm run dev

# Push your branch
git push -u origin feature/your-feature-name

# Open PR on GitHub
# IMPORTANT: 
# - Base: dev (NEVER main!)
# - Compare: feature/your-feature-name
# - Follow the PR template
# - Add relevant labels

​

Branch Strategy

​

Overview

​

Branch Protection Rules

​

Main Branch (Production)

• Protection Level: Maximum
• Requirements:
  • PR from dev branch only
  • All CI/CD checks must pass
  • No direct commits allowed
  • Admin override only in emergencies
• Auto-deployment: Merges trigger production deploy

​

Dev Branch (Development)

• Protection Level: Moderate
• Requirements:
  • PR from feature branches
  • CI checks must pass
  • No approval required (trust-based)
  • Direct commits allowed for hotfixes
• Auto-deployment: Merges trigger dev environment deploy

​

Feature Branches

• Protection Level: None
• Guidelines:
  • Always create from dev
  • Use descriptive names
  • Delete after merge
  • Keep focused on single feature/fix

​

Working with Supabase

​

Creating Migrations

1. Write Migration:
   • Open Supabase dashboard
   • Go to SQL Editor
   • Write and test your SQL changes
   • Save the SQL to a file in your repo
2. Version Control:
   Copy

   # Save migration in your repository
   mkdir -p migrations
   echo "-- Your SQL here" > migrations/$(date +%Y%m%d)_your_migration_name.sql
   

3. Apply Migration:
   • For immediate changes: Run in SQL Editor
   • For review: Include in PR
   • Team lead will apply during deployment

​

Development vs Production Data

1. Test Accounts: Always use emails containing ‘test’
2. Data Isolation: Create test data that’s clearly marked
3. Read-Only First: Use SELECT before UPDATE/INSERT
4. Clean Up: Remove test data after development

-- Good: Using test accounts
SELECT * FROM students WHERE email LIKE '%test%';

-- Good: Clearly marked test data
INSERT INTO schools (name, is_test) 
VALUES ('Test University', true);

-- Bad: Operating on real user data
UPDATE students SET ... WHERE email NOT LIKE '%test%';

​

Working with the Web App

​

Local Development

# 1. Start the dev server
cd ~/findu/web_app
npm run dev

# 2. Open http://localhost:5173
# 3. Make changes - hot reload active

​

Adding New Features

# 1. Create component
touch src/pages/NewFeature.tsx

# 2. Add route
# Edit src/App.tsx

# 3. Update navigation
# Edit src/components/nav-main.tsx

​

Working with AI Development Tools

​

Claude Code (MCP)

# Available MCP tools:
mcp__supabase__search_docs      # Search Supabase documentation
mcp__supabase__list_tables      # View database schema
mcp__supabase__execute_sql      # Run SQL queries
mcp__supabase__apply_migration  # Apply database changes

​

Using MCP Effectively

-- Use MCP to create tables
mcp__supabase__apply_migration 
  name: "create_features_table"
  query: "CREATE TABLE features (...);"

​

Git Workflow

​

Branch Naming

• feature/description - New features
• fix/description - Bug fixes
• chore/description - Maintenance tasks
• docs/description - Documentation only

​

Commit Messages

# Good
git commit -m "Add scholarship filtering by deadline"
git commit -m "Fix navigation menu z-index issue"
git commit -m "Update developer setup documentation"

# Bad
git commit -m "Fixed stuff"
git commit -m "WIP"
git commit -m "asdf"

​

PR Guidelines

​

Deployment Process

​

Development Deployment

​

Production Deployment

​

Service URLs

• Web App: findu-web-dev.up.railway.app
• ML API: findu-matching-dev.up.railway.app

• Web App: findu-web-production.up.railway.app
• ML API: findu-matching-production.up.railway.app
• iOS App: App Store

​

Common Tasks

​

Adding Environment Variables

# 1. Add to .env.local
echo "NEW_VAR=value" >> ~/.findu/.env.local

# 2. Update templates
# Edit dev-tools/templates/.env.local.template

​

Debugging Issues

# Check environment
./findu env status

# Update MCP
./findu update mcp

# Verify credentials
supabase status

# Clear caches
rm -rf node_modules
npm install

# Check for type errors
npm run typecheck

​

Best Practices

​

Code Quality

1. Follow existing patterns - Check nearby code
2. Write tests - Especially for critical paths
3. Handle errors gracefully - Users should never see crashes
4. Optimize for performance - Profile before optimizing

​

Security

1. Never commit secrets - Use environment variables
2. Validate all inputs - Both client and server side
3. Use RLS policies - Supabase row-level security
4. Regular dependency updates - Keep packages current

​

Team Collaboration

1. Communicate in PRs - Document your thinking
2. Review thoughtfully - Test locally when needed
3. Ask questions - No question is too simple
4. Share knowledge - Update docs as you learn

​

Useful Resources