​

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

​

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

# 1. Check if shadcn/ui has it
npx shadcn-ui@latest add [component]

# 2. Or create custom
mkdir src/components/custom
touch src/components/custom/MyComponent.tsx

# 1. Add types
# Edit src/types/database.types.ts

# 2. Create hook
touch src/hooks/useNewFeature.ts

# 3. Use in component

​

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 (...);"

-- Query data directly
mcp__supabase__execute_sql
  query: "SELECT * FROM students LIMIT 10;"

-- Search Supabase docs
mcp__supabase__search_docs
  graphql_query: "{ searchDocs(query: \"RLS policies\") { ... } }"

​

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

# Add to GitHub Organization Secrets:
# - NEW_VAR_DEV (for development)
# - NEW_VAR_PROD (for production)

# Update workflows to use them

# Add in Railway dashboard:
# 1. Go to project settings
# 2. Add environment variable
# 3. Redeploy service

​

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