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

# Web App Overview

> Architecture and concepts for the FindU partner dashboard

# Web App Overview

The FindU web app is a React-based dashboard that enables schools, partners, and admissions teams to manage their presence, view analytics, and communicate with prospective students.

<Note>
  **Tech Stack**: React 19 + TypeScript + Vite + Tailwind CSS + shadcn/ui
  **Features**: Partner management, team collaboration, real-time analytics, messaging center
</Note>

## Architecture

The web app follows a modern React architecture with these key principles:

### Component Structure

```
src/
├── components/      # Reusable UI components
│   ├── ui/         # Base shadcn/ui components
│   └── custom/     # App-specific components
├── features/       # Feature-based organization
│   ├── analytics/  # Analytics dashboard
│   ├── campaigns/  # Student management
│   ├── messaging/  # Real-time chat
│   ├── onboarding/ # Partner onboarding wizard
│   ├── profile/    # School profile builder
│   └── settings/   # Team & organization settings
├── hooks/          # Custom React hooks
├── contexts/       # React contexts (auth, team)
├── lib/            # Utilities and helpers
└── types/          # TypeScript definitions
```

### State Management

We use a combination of:

* **React Context** for global state:
  * `AuthContext`: Authentication and user data
  * `TeamContext`: Multi-team/organization support
* **Local state** for component-specific data
* **Supabase real-time** for live updates (messages, analytics)
* **Custom hooks** for shared logic:
  * `useAuth()`: Authentication state
  * `usePermissions()`: Role-based access
  * `useTeamContext()`: Current team/entity

### Data Flow

```mermaid theme={null}
graph TD
    A[Supabase] --> B[React App]
    B --> C[Context Providers]
    C --> D[Feature Components]
    D --> E[UI Components]
    E --> F[User Actions]
    F --> A
```

## Key Features

### Partner Dashboard

* **Real-time Analytics**: Student interactions, engagement metrics
* **Campaign Management**: Track and filter prospective students
* **Geographic Visualization**: Interactive state map of reach
* **Insights Panel**: Top concerns, popular features

### Team Management

* **Multi-Organization Support**: Universities, companies, nonprofits
* **Entity Management**: Departments, programs, offices
* **Role-Based Access**: Admin, Staff, Counselor roles
* **Invitation System**: Email-based team invitations

### Messaging Center

* **Real-time Chat**: Direct communication with students
* **Bulk Messaging**: Reach multiple students at once
* **Message Templates**: Quick responses to common questions
* **Conversation History**: Full chat records

### Profile Builder

* **Dynamic Sections**: Drag-and-drop content blocks
* **Live Preview**: Mobile-optimized preview
* **Media Management**: Images, statistics, highlights
* **Partner Tags**: Categorization and discovery

### Scholarship Management

* **Create & Edit**: Full scholarship lifecycle
* **Tracking**: Impressions, saves, applications
* **Requirements**: Eligibility criteria
* **Deadlines**: Open/close date management

### Authentication Flow

1. User logs in via Supabase Auth
2. Auth state managed by context
3. Protected routes check permissions
4. Role-based UI rendering

### Real-time Updates

The app uses Supabase subscriptions for:

* New messages
* Student interactions
* Analytics updates
* Team member changes

## Development Patterns

### Component Patterns

```tsx theme={null}
// Feature component with permissions check
export function CampaignsPage() {
  const { hasPermission } = usePermissions();
  const { data, loading } = useCampaigns();
  
  if (!hasPermission('view_campaigns')) {
    return <AccessDenied />;
  }
  
  if (loading) return <LoadingState />;
  
  return (
    <PageLayout>
      <StudentTable data={data} />
    </PageLayout>
  );
}
```

### Team Context Usage

```tsx theme={null}
// Multi-team support
export function Dashboard() {
  const { currentTeam, switchTeam } = useTeamContext();
  
  return (
    <div>
      <TeamSwitcher 
        current={currentTeam}
        onSwitch={switchTeam}
      />
      <DashboardContent teamId={currentTeam.id} />
    </div>
  );
}
```

### Error Handling

* Global error boundary for crashes
* Toast notifications for user feedback
* Graceful degradation for missing data

## Performance Considerations

### Code Splitting

* Route-based splitting with React.lazy
* Component lazy loading for heavy features
* Dynamic imports for optional features

### Optimization Techniques

* React.memo for expensive components
* useMemo/useCallback for computations
* Virtual scrolling for large lists
* Image lazy loading

### Caching Strategy

* SWR pattern for data fetching
* Local storage for user preferences
* Session storage for temporary data

## Deployment Architecture

The web app follows a dev/main deployment pattern:

### Development Environment

* **Branch**: `dev`
* **URL**: `findu-web-dev.up.railway.app`
* **Auto-deploy**: On merge to dev
* **Purpose**: Testing new features

### Production Environment

* **Branch**: `main`
* **URL**: `findu-web-production.up.railway.app`
* **Auto-deploy**: On merge to main
* **Requirements**: PR from dev branch

### Build Configuration

```json theme={null}
// vite.config.ts
{
  build: {
    outDir: 'dist',
    sourcemap: true
  }
}
```

## Next Steps

* [Component Library Guide](/web-app/components)
* [State Management Patterns](/web-app/state-management)
* [Styling with Tailwind](/web-app/styling-guide)
* [Testing Strategies](/web-app/testing)