​

Web App Overview

​

Architecture

​

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

• 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

​

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

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

​

Development Patterns

​

Component Patterns

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

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

​

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

// vite.config.ts
{
  build: {
    outDir: 'dist',
    sourcemap: true
  }
}

​

Next Steps

• Component Library Guide
• State Management Patterns
• Styling with Tailwind
• Testing Strategies