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

# Development Guide

> Development workflow and standards for FindU team

# FindU Development Guide

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

## Repository Overview

<CardGroup cols={2}>
  <Card title="web_app" icon="browser">
    React dashboard for partners

    * Partner analytics
    * Messaging interface
    * Profile management
    * Scholarship tools
  </Card>

  <Card title="ios_app" icon="mobile">
    Native iOS app for students

    * College swiping
    * Student messaging
    * Profile creation
    * Social features
  </Card>

  <Card title="matching-algorithm" icon="brain">
    ML matching engine

    * Recommendation API
    * Learning algorithms
    * Performance optimization
    * Mobile endpoints
  </Card>

  <Card title="data_scraping" icon="database">
    Data collection & enrichment

    * College data updates
    * Image scraping
    * AI-powered enhancements
    * Automated pipelines
  </Card>
</CardGroup>

## Development Process

### 1. Starting New Work

<Steps>
  <Step title="Check Current Sprint">
    * Review sprint board for assigned tasks
    * Check with team lead for priorities
    * Understand acceptance criteria
  </Step>

  <Step title="Pull Latest Changes">
    Always start from updated dev branch:

    ```bash theme={null}
    git checkout dev
    git pull origin dev
    ```
  </Step>

  <Step title="Create Feature Branch">
    Use descriptive branch names:

    ```bash theme={null}
    git checkout -b feature/add-scholarship-filters
    git checkout -b fix/profile-creation-bug
    git checkout -b chore/update-dependencies
    ```
  </Step>
</Steps>

### 2. Making Changes

Always follow our branch strategy:

```mermaid theme={null}
graph LR
    A[dev branch] --> B[feature/your-branch]
    B --> C[Open PR to dev]
    C --> D[Review & Merge]
    D --> A
    A --> E[Weekly merge to main]
    E --> F[Production deploy]
```

<Warning>
  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`.
</Warning>

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

<Tabs>
  <Tab title="TypeScript/React">
    ```typescript theme={null}
    // 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
    }
    ```
  </Tab>

  <Tab title="Swift/iOS">
    ```swift theme={null}
    // Good: SwiftUI best practices
    struct StudentCardView: View {
        @StateObject var viewModel: StudentCardViewModel
        
        var body: some View {
            // Clean, composable views
        }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Good: Type hints and docstrings
    def calculate_match_score(
        student: StudentProfile,
        school: School
    ) -> float:
        """Calculate match score between student and school.
        
        Returns score between 0.0 and 1.0
        """
        # Implementation
    ```
  </Tab>
</Tabs>

### 4. Manual Testing

Before submitting your PR:

* [ ] Test your changes locally
* [ ] Verify the feature works as expected
* [ ] Check for console errors
* [ ] Test edge cases and error scenarios
* [ ] Verify mobile responsiveness (if web)
* [ ] Test on actual devices (if iOS)

### 5. Pull Request

Use our simplified PR template:

```markdown theme={null}
## What does this PR do?
[Brief description]

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

## How did you test this?
- [ ] Manually tested locally
- [ ] What I tested: [describe what you clicked, tried, verified]
- [ ] Edge cases tested: [any error scenarios, empty states, etc.]

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

## Review Process

What happens after you open a PR:

<Steps>
  <Step title="Automated Checks">
    GitHub Actions will run:

    * Linting
    * Type checking
    * Security checks
    * Build verification
  </Step>

  <Step title="Code Review">
    Team members will review:

    * Code quality and standards
    * Architecture alignment
    * Performance impact
    * Security considerations
  </Step>

  <Step title="Manual Testing">
    * Test changes thoroughly locally
    * Deploy to dev environment and test
    * Check that existing features still work
    * Mobile app: test on real devices
  </Step>

  <Step title="Merge & Deploy">
    Once approved:

    * PR merged to dev
    * Auto-deployed to dev environment
    * Monitor for issues
    * Plan production release
  </Step>
</Steps>

## Team Communication

<CardGroup cols={2}>
  <Card title="Daily Standup" icon="users">
    Share progress and blockers

    * What you completed
    * What you're working on
    * Any blockers
  </Card>

  <Card title="Technical Help" icon="circle-question">
    Getting unstuck:

    * Ask in #dev-help
    * Pair with teammates
    * Schedule 1:1 with lead
  </Card>

  <Card title="Design Decisions" icon="compass">
    For architecture questions:

    * Document in PR
    * Discuss in tech meeting
    * Create ADR if needed
  </Card>

  <Card title="Sprint Planning" icon="calendar">
    Weekly planning:

    * Review upcoming work
    * Estimate tasks
    * Identify dependencies
  </Card>
</CardGroup>

## Development Standards

### Code Quality

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

### Quality Assurance

* Test your changes thoroughly
* Try to break your own feature
* Test edge cases and error states
* Verify on different screen sizes
* Check performance impact

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

```mermaid theme={null}
graph TB
    A[Feature Branch] --> B[Pull Request to dev]
    B --> C{Build & Lint Pass?}
    C -->|Yes| D[Merge to dev]
    C -->|No| E[Fix & retry]
    D --> F[Auto-deploy to dev environment]
    F --> G[Team Testing on dev]
    G --> H[Weekly: PR dev to main]
    H --> I{All checks pass?}
    I -->|Yes| J[Merge to main]
    I -->|No| K[Fix issues on dev]
    J --> L[Auto-deploy to production]
    L --> M[Monitor production]
```

### Environment Details

<Steps>
  <Step title="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`
  </Step>

  <Step title="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`
  </Step>

  <Step title="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)
  </Step>
</Steps>

<Note>
  **Remember**: We're building something amazing together. Quality over speed, communication over assumptions.
</Note>