​

Developer Workflow Guide

​

Daily Development Flow

# Switch to development environment
./findu env switch dev

# Pull latest changes from dev branch
cd ~/findu/supabase && git checkout dev && git pull
cd ~/findu/web_app && git checkout dev && git pull

# Update dependencies
./findu update deps

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

# Run component tests
./findu test web

# Test against dev Supabase
npm run dev

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

# Open PR targeting dev branch
# - Base: dev (not main!)
# - Compare: feature/your-feature-name
# Preview branch will be created automatically

​

Branch Strategy

​

Overview

​

Branch Protection Rules

1. main branch:
   • Requires PR with review
   • CI/CD must pass
   • No direct pushes
   • Deploys to production automatically
2. dev branch:
   • Requires PR (no review needed)
   • CI must pass
   • Direct pushes allowed for fixes
   • Deploys to dev Supabase automatically
3. feature branches:
   • No protection
   • Always branch from dev
   • Delete after merge

​

Working with Supabase

​

Creating Migrations

# 1. Make sure you're in dev
./findu env switch dev

# 2. Create a new migration
cd ~/findu/supabase
supabase migration new your_migration_name

# 3. Edit the migration file
# migrations/[timestamp]_your_migration_name.sql

# 4. Apply locally
supabase db push

# 5. Test your changes
# Then commit and push

​

Using Preview Branches

1. Automatic Creation: Opens PR → Preview branch created
2. Unique URL: Each PR gets its own Supabase instance
3. Schema Only: No production data is copied
4. Auto Cleanup: Deleted when PR is closed/merged

​

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 Claude Code (MCP)

​

Initial Setup

# 1. Install Claude Code desktop app
# 2. Update MCP configuration
./findu update mcp

# 3. Restart Claude Code
# 4. You now have Supabase access!

​

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

​

To Development

​

To Production

​

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

​

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