> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinfindu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Guide

> Common development workflows and best practices

# Developer Workflow Guide

This guide covers common development workflows and best practices for working on the FindU platform.

## Daily Development Flow

<Steps>
  <Step title="Start your day">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Create a feature branch">
    ```bash theme={null}
    # Create branch from dev (not main!)
    git checkout dev
    git pull origin dev
    git checkout -b feature/your-feature-name
    ```
  </Step>

  <Step title="Make your changes">
    * Write code
    * Add tests
    * Update documentation
  </Step>

  <Step title="Test locally">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Open a PR">
    ```bash theme={null}
    # 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
    ```
  </Step>
</Steps>

## Branch Strategy

### Overview

FindU uses a three-tier branch strategy:

```mermaid theme={null}
graph LR
    A[feature/*] -->|PR| B[dev]
    B -->|Auto PR| C[main]
    C -->|Deploy| D[Production]
```

### 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

When you need to modify the database, you have two options:

<Tabs>
  <Tab title="Option A: Dashboard (Easy)">
    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**:
       ```bash theme={null}
       # 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
  </Tab>

  <Tab title="Option B: CLI (Advanced)">
    1. **Generate Migration**:
       ```bash theme={null}
       cd ~/findu/supabase
       supabase migration new your_migration_name
       ```

    2. **Write SQL**:
       Edit the generated file in `supabase/migrations/`

    3. **Test Locally**:
       ```bash theme={null}
       supabase db reset  # Rebuilds from scratch
       # or
       supabase db push   # Just new migrations
       ```

    4. **Apply to Production**:
       Include in PR for deployment
  </Tab>
</Tabs>

<Warning>
  Always test migrations in development first! Production migrations can't be easily rolled back.
</Warning>

### Development vs Production Data

Since we use production Supabase directly, follow these guidelines:

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

```sql theme={null}
-- 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

```bash theme={null}
# 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

<Tabs>
  <Tab title="New Page">
    ```bash theme={null}
    # 1. Create component
    touch src/pages/NewFeature.tsx

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

    # 3. Update navigation
    # Edit src/components/nav-main.tsx
    ```
  </Tab>

  <Tab title="New Component">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="New API Integration">
    ```bash theme={null}
    # 1. Add types
    # Edit src/types/database.types.ts

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

    # 3. Use in component
    ```
  </Tab>
</Tabs>

## Working with AI Development Tools

### Claude Code (MCP)

Claude Code provides direct Supabase integration:

```bash theme={null}
# 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

<CodeGroup>
  ```sql create-table theme={null}
  -- Use MCP to create tables
  mcp__supabase__apply_migration 
    name: "create_features_table"
    query: "CREATE TABLE features (...);"
  ```

  ```sql query-data theme={null}
  -- Query data directly
  mcp__supabase__execute_sql
    query: "SELECT * FROM students LIMIT 10;"
  ```

  ```typescript search-docs theme={null}
  -- Search Supabase docs
  mcp__supabase__search_docs
    graphql_query: "{ searchDocs(query: \"RLS policies\") { ... } }"
  ```
</CodeGroup>

## Git Workflow

### Branch Naming

Follow these conventions:

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

### Commit Messages

Write clear, descriptive commits:

```bash theme={null}
# 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

<Checklist>
  * [ ] Descriptive title
  * [ ] Clear description of changes
  * [ ] Link to related issues
  * [ ] Tests pass
  * [ ] Documentation updated
  * [ ] Screenshots for UI changes
</Checklist>

## Deployment Process

### Development Deployment

```mermaid theme={null}
graph LR
    A[Push to dev branch] --> B[GitHub Actions CI]
    B --> C{All checks pass?}
    C -->|Yes| D[Auto-deploy via Railway]
    C -->|No| E[Fix failing checks]
    D --> F[Dev environment updated]
    F --> G[Team testing]
```

### Production Deployment

```mermaid theme={null}
graph LR
    A[Create PR: dev → main] --> B[CI/CD Checks]
    B --> C{Pass?}
    C -->|Yes| D[Team Review]
    C -->|No| E[Fix on dev]
    D --> F[Merge to main]
    F --> G[Railway auto-deploy]
    G --> H[Production live]
    H --> I[Monitor metrics]
```

### Service URLs

**Development Environment:**

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

**Production Environment:**

* 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

<Tabs>
  <Tab title="Local Development">
    ```bash theme={null}
    # 1. Add to .env.local
    echo "NEW_VAR=value" >> ~/.findu/.env.local

    # 2. Update templates
    # Edit dev-tools/templates/.env.local.template
    ```
  </Tab>

  <Tab title="CI/CD">
    ```bash theme={null}
    # Add to GitHub Organization Secrets:
    # - NEW_VAR_DEV (for development)
    # - NEW_VAR_PROD (for production)

    # Update workflows to use them
    ```
  </Tab>

  <Tab title="Railway">
    ```bash theme={null}
    # Add in Railway dashboard:
    # 1. Go to project settings
    # 2. Add environment variable
    # 3. Redeploy service
    ```
  </Tab>
</Tabs>

### Debugging Issues

<AccordionGroup>
  <Accordion title="Database connection issues">
    ```bash theme={null}
    # Check environment
    ./findu env status

    # Update MCP
    ./findu update mcp

    # Verify credentials
    supabase status
    ```
  </Accordion>

  <Accordion title="Build failures">
    ```bash theme={null}
    # Clear caches
    rm -rf node_modules
    npm install

    # Check for type errors
    npm run typecheck
    ```
  </Accordion>

  <Accordion title="Preview branch not working">
    Check:

    * PR is from a branch in the same repo
    * Supabase Branching 2.0 is enabled
    * No migration conflicts
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Supabase Docs" icon="database" href="https://supabase.com/docs">
    Database, auth, and storage reference
  </Card>

  <Card title="React Docs" icon="react" href="https://react.dev">
    React patterns and best practices
  </Card>

  <Card title="Tailwind CSS" icon="palette" href="https://tailwindcss.com">
    Utility-first CSS framework
  </Card>

  <Card title="FindU Slack" icon="slack" href="#">
    Internal team communication
  </Card>
</CardGroup>

***

Questions? Need help? Don't hesitate to ask in #dev-help on Slack!