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

# Architecture Overview

> Understanding FindU's multi-repository system architecture

# FindU Architecture

FindU uses a microservices architecture with separate repositories for each major component. This enables independent development, deployment, and scaling.

## System Overview

```mermaid theme={null}
graph TB
    subgraph "Client Applications"
        iOS[iOS App<br/>Swift/SwiftUI]
        Web[Partner Dashboard<br/>React/TypeScript]
        Staff[Internal Tools<br/>React/TypeScript]
    end
    
    subgraph "Backend Services"
        API[Matching API<br/>Python/FastAPI]
        Edge[Edge Functions<br/>TypeScript/Deno]
    end
    
    subgraph "Data Layer"
        DB[(Supabase<br/>PostgreSQL)]
        Storage[File Storage<br/>Supabase Storage]
    end
    
    subgraph "External Services"
        College[College Scorecard API]
        Wiki[Wikipedia API]
    end
    
    iOS --> DB
    iOS --> API
    Web --> DB
    Web --> Edge
    Staff --> DB
    API --> DB
    Edge --> DB
    API --> College
    Edge --> Wiki
    DB --> Storage
```

## Repository Structure

Each component lives in its own repository:

<CardGroup cols={2}>
  <Card title="ios_app" icon="mobile">
    **Purpose**: Native iOS application for students

    * SwiftUI interface
    * Supabase SDK integration
    * Real-time messaging
    * Apple/Google auth
  </Card>

  <Card title="web_app" icon="browser">
    **Purpose**: Partner & staff web dashboard

    * React 19 + TypeScript
    * Partner portal features
    * Internal admin tools
    * Analytics & reporting
  </Card>

  <Card title="matching-algorithm" icon="brain">
    **Purpose**: ML-powered matching engine

    * Python FastAPI service
    * Student-school matching
    * Recommendation engine
    * Hosted on Railway
  </Card>

  <Card title="data_scraping" icon="globe">
    **Purpose**: Data collection scripts

    * College Scorecard sync
    * Image scraping
    * AI-powered data enrichment
    * Railway scheduled jobs
  </Card>

  <Card title="docs" icon="book">
    **Purpose**: This documentation site

    * Mintlify framework
    * API references
    * Developer guides
    * Architecture docs
  </Card>
</CardGroup>

## Data Flow

### 1. Student Matching Flow

```mermaid theme={null}
sequenceDiagram
    participant Student as iOS App
    participant ML as Matching API
    participant DB as Supabase
    
    Student->>DB: Fetch profile
    Student->>ML: Request recommendations
    ML->>DB: Get school data
    ML->>ML: Calculate matches
    ML-->>Student: Return recommendations
    Student->>DB: Save interactions
```

### 2. Partner Management Flow

```mermaid theme={null}
sequenceDiagram
    participant Partner as Web Dashboard
    participant DB as Supabase
    participant Edge as Edge Functions
    
    Partner->>DB: Authenticate
    Partner->>DB: Fetch analytics
    Partner->>Edge: Send message
    Edge->>DB: Store message
    Edge-->>Partner: Confirm sent
```

## Environment Architecture

FindU operates with two primary environments:

### Development Environment

* **Branch**: `dev`
* **Database**: Production Supabase (with test data)
* **Deployment**: Automatic from dev branch via Railway
* **URLs**: `*-dev.railway.app`
* **Purpose**: Testing new features before production
* **Access**: All developers

### Production Environment

* **Branch**: `main`
* **Database**: Production Supabase (50,000+ students)
* **Deployment**: Automatic from main branch via Railway
* **URLs**: `findu.app`, `*-production.railway.app`
* **Data**: Live user data
* **Access**: Protected, requires PR from dev

<Warning>
  Both environments use the same Supabase instance. Always use test accounts (emails containing 'test') when developing to avoid affecting real users.
</Warning>

### Safe Development Practices

* Use test accounts for all development
* Mark test data clearly
* Test features on dev environment first
* Monitor metrics after production deploys
* Clean up test data regularly

## Key Design Decisions

### Why Multiple Repositories?

1. **Independent Deployment**: Each service can be deployed separately
2. **Team Autonomy**: Teams can work without blocking each other
3. **Technology Freedom**: Use the best tool for each job
4. **Easier Scaling**: Scale services independently

### Why Supabase?

1. **Real-time Features**: Built-in websockets for messaging
2. **Auth Integration**: Handles authentication complexity
3. **PostgreSQL Power**: Full SQL capabilities
4. **Edge Functions**: Serverless compute at the edge

### Why This Stack?

* **iOS Native**: Better performance and UX than React Native
* **React for Web**: Fast development, great ecosystem
* **Python for ML**: Best libraries for data science
* **Railway Hosting**: Simple deployment, good DX

## Security Architecture

```mermaid theme={null}
graph LR
    subgraph "Public Access"
        Student[Students]
        Partner[Partners]
    end
    
    subgraph "Authentication Layer"
        Auth[Supabase Auth]
        RLS[Row Level Security]
    end
    
    subgraph "Internal Only"
        Staff[Staff Tools]
        Admin[Admin Panel]
    end
    
    Student --> Auth
    Partner --> Auth
    Auth --> RLS
    RLS --> DB[(Database)]
    Staff --> Admin
    Admin --> DB
```

## Deployment Pipeline

All repositories follow a consistent dev/main deployment pattern:

```mermaid theme={null}
graph TB
    subgraph "Development Flow"
        A[Local Development] --> B[Feature Branch]
        B --> C[PR to dev]
        C --> D{CI Checks}
        D -->|Pass| E[Merge to dev]
        D -->|Fail| F[Fix & Retry]
        E --> G[Auto-deploy to dev environment]
    end
    
    subgraph "Production Flow"
        G --> H[Testing on dev]
        H --> I[Weekly PR: dev → main]
        I --> J{All checks pass?}
        J -->|Yes| K[Merge to main]
        J -->|No| L[Fix on dev]
        K --> M[Auto-deploy to production]
        M --> N[Monitor metrics]
    end
```

### Deployment Automation

**Development (dev branch):**

* Automatic deployment on merge
* Railway dev services
* No approval required
* Immediate feedback

**Production (main branch):**

* Automatic deployment on merge
* Railway production services
* Requires PR from dev
* Protected branch rules

## Next Steps

<CardGroup cols={2}>
  <Card title="Developer Setup" icon="code" href="/developer/initial-setup">
    Get your local environment running
  </Card>

  <Card title="Repository Guide" icon="book" href="/developer/workflow-guide">
    Learn when to work in which repo
  </Card>
</CardGroup>