Skip to content

Latest commit

 

History

History
541 lines (407 loc) · 11.7 KB

MENTAL_MODEL.md

File metadata and controls

541 lines (407 loc) · 11.7 KB
theme background class highlighter lineNumbers info drawings transition title
default
text-center
shiki
false
## IlliniHunt Mental Model A comprehensive guide to understanding the Product Hunt-style platform for University of Illinois
persist
slide-left
IlliniHunt Mental Model

IlliniHunt Mental Model

🧠 Understanding the Codebase Architecture

A comprehensive guide for vibe coding on the University of Illinois project discovery platform

Press Space for next page

layout: center class: text-center

🎯 What is IlliniHunt?

Core Concept

Product Hunt for University of Illinois

  • 🎓 University-Focused: @illinois.edu authentication only
  • 🎯 Problem-Centered: Categories based on problems solved
  • 💬 Community Engagement: Voting, comments, collections
  • 📱 Mobile-First: Responsive design

Key Features

  • ✅ Project submission & discovery
  • ✅ Real-time voting system
  • ✅ Threaded comments (3 levels)
  • ✅ User profiles & portfolios
  • ✅ Project collections & bookmarks
  • ✅ Admin dashboard

layout: two-cols

🏗️ Tech Stack

Frontend

  • React 18 + TypeScript
  • Vite for build tooling
  • Tailwind CSS + shadcn/ui
  • React Router for routing
  • React Hook Form + Zod validation

Backend & Database

  • Supabase (PostgreSQL + Auth)
  • Row Level Security (RLS)
  • Real-time subscriptions
  • Google OAuth with domain restrictions

::right::

Deployment & DevOps

  • Vercel for hosting
  • GitHub Actions for CI/CD
  • TypeScript strict mode
  • ESLint for code quality

Design System

  • UIUC Orange: #FF6B35
  • UIUC Blue: #13294B
  • Lucide React icons
  • Mobile-first responsive design

layout: center

📊 Database Schema

Core Tables

users (extends Supabase auth.users)
├── id, email, username, full_name
├── avatar_url, bio, github_url
├── year_of_study, department

projects (main content)
├── name, tagline, description
├── category_id, user_id
├── upvotes_count, comments_count

votes (user voting)
├── user_id, project_id (unique)

comments (threaded discussions)
├── content, user_id, project_id
├── parent_id, thread_depth

Organization Tables

categories (8 problem-focused)
├── Learning & Education Tools 🎓
├── Social & Communication 👥
├── Productivity & Organization 📅
├── Health & Wellness ❤️
├── Creative & Entertainment 🎨
├── Research & Data Analysis 📊
├── Business & Entrepreneurship 📈
└── Emerging Technology ⚡

collections & bookmarks
├── collections: user_id, name, is_public
├── bookmarks: user_id, project_id
└── collection_projects: many-to-many

layout: two-cols

🎨 User Flows & Pages

Public Pages

  • / - HomePage: Hero + Featured + Categories
  • /project/:id - ProjectDetailPage: Full project view
  • /user/:id - UserProfilePage: Public user profile

Protected Pages

  • /submit - SubmitProjectPage: Project submission
  • /dashboard - DashboardPage: Project management
  • /profile/edit - EditProfilePage: Profile editing
  • /edit-project/:id - EditProjectPage: Project editing
  • /collections - CollectionsPage: Collection management

::right::

Key User Journeys

1. Project Discovery

HomePage → Category → ProjectGrid → ProjectCard → ProjectDetail

2. Project Submission

Login → SubmitProject → ProjectForm → Success → Redirect

3. Engagement

ProjectDetail → Vote/Comment/Bookmark → Real-time Updates

4. Management

Dashboard → Stats → Edit/Delete → Profile Management

layout: center

⚡ Real-time Features

Voting System

  • Optimistic UI: Immediate vote count updates
  • Real-time sync: RealtimeVotesContext manages live updates
  • Error handling: Rollback on failure, sync validation
  • Database triggers: Auto-update upvotes_count

Comment System

  • Threaded comments: 3 levels deep
  • Soft deletion: is_deleted flag
  • Real-time updates: New comments appear live

State Management

// Context providers
AuthProvider          // User authentication
ErrorProvider         // Global error handling
RealtimeVotesProvider // Live vote updates
AuthPromptProvider    // Auth prompts

// Custom hooks
useAuth()             // Authentication state
useRealtimeVotes()    // Vote management
useWindowSize()       // Responsive utilities

layout: two-cols

🛡️ Security & Authentication

Authentication Flow

Google OAuth → @illinois.edu validation → 
User profile creation → Session management

Row Level Security (RLS)

  • Users: View all, update own profile
  • Projects: Public read, own CRUD operations
  • Votes/Comments: Own operations only
  • Collections: Own collections, public visible

::right::

Protected Routes

const ProtectedRoute = ({ children }) => {
  const { user, loading } = useAuth()
  
  if (loading) return <LoadingSpinner />
  if (!user) return <Navigate to="/" />
  
  return <>{children}</>
}

Security Issues (Current)

  • 🔴 RLS disabled on comments table
  • 🔴 Client-side only domain restriction
  • 🔴 20+ redundant auth calls per page load

layout: center

🎨 UI/UX Patterns

Design System

  • Colors: UIUC Orange (#FF6B35), UIUC Blue (#13294B)
  • Components: shadcn/ui primitives
  • Icons: Lucide React icons
  • Responsive: Mobile-first with Tailwind

Key Components

  • ProjectCard: Main project display with voting overlay
  • VoteButton: Optimistic voting with real-time sync
  • ProjectForm: Comprehensive submission/editing
  • CommentList: Threaded comment display
  • UserMenu: Profile dropdown navigation

Error Handling

// Global error boundary
<ErrorBoundary>
  <App />
</ErrorBoundary>

// Service error handling
const { handleServiceError, showSuccess } = useError()

// Toast notifications
<Toaster position="top-right" richColors />

Performance Optimizations

  • Code splitting: Lazy-loaded pages
  • Preloading: Critical routes on interaction
  • Debouncing: Search queries (300ms)
  • Caching: Profile data in localStorage

layout: center

🔧 Development Patterns

Service Layer Pattern

// database.ts - Abstracts all Supabase operations
export const ProjectsService = {
  getProjects: (filters) => supabase.from('projects').select('*'),
  createProject: (data) => supabase.from('projects').insert(data),
  voteProject: (id) => supabase.from('votes').insert({project_id: id}),
  // ... more methods
}

Form Handling

// React Hook Form + Zod validation
const form = useForm<ProjectFormData>({
  resolver: zodResolver(projectSchema)
})

const onSubmit = async (data) => {
  // Optimistic UI updates
  // Service calls
  // Error handling
}

Real-time Updates

// RealtimeVotesContext
const { getVoteData, updateVoteCount, updateUserVote } = useRealtimeVotesContext()

// Subscribe to vote changes
useEffect(() => {
  const subscription = supabase
    .channel('votes')
    .on('postgres_changes', { event: '*', schema: 'public', table: 'votes' }, 
        handleVoteChange)
    .subscribe()
    
  return () => subscription.unsubscribe()
}, [])

layout: center

🎯 Vibe Coding Tips

When Adding Features

  1. Check existing patterns: Look at similar components first
  2. Use service layer: Add functions to database.ts
  3. Follow RLS: Ensure proper security policies
  4. Optimistic UI: Update UI immediately, handle errors gracefully
  5. Real-time: Consider if feature needs live updates

Common Patterns

  • Protected content: Wrap in ProtectedRoute
  • Loading states: Use consistent loading spinners
  • Error handling: Use useError hook for consistent UX
  • Form validation: Use Zod schemas with React Hook Form
  • Real-time data: Use useRealtimeVotesContext for vote-related features

File Organization

src/
├── components/         # Reusable UI components
│   ├── auth/          # Authentication components
│   ├── project/       # Project-related components
│   ├── comment/       # Comment system components
│   └── ui/            # shadcn/ui primitives
├── contexts/          # React Context providers
├── hooks/             # Custom React hooks
├── lib/               # Utilities and configurations
├── pages/             # Route components
└── types/             # TypeScript type definitions

Key Commands

npm run dev          # Start development server
npm run build        # Production build
npm run type-check   # TypeScript validation
npm run lint         # ESLint check

layout: center

🚨 Current Issues & Opportunities

Critical Issues

  • 🔴 Performance: 20+ redundant auth calls per page load
  • 🔴 Security: RLS disabled on comments table
  • 🔴 Auth: Client-side only domain restriction
  • 🟡 Voting: Potential sync issues with optimistic updates

Performance Problems

  • Loading screens for logged-in users
  • Frozen submit buttons
  • Redundant database calls
  • Missing rate limiting

Future Enhancements

  • 🔮 Course Integration: Connect projects to UIUC courses
  • 🔮 Faculty Collaboration: Professor and research mentor features
  • 🔮 Industry Partnerships: Connect projects to career opportunities
  • 🔮 Mobile App: Native iOS/Android applications
  • 🔮 Advanced Search: Tag system and enhanced filtering
  • 🔮 Admin Panel: Content moderation and featured project curation

layout: center

🎉 Key Takeaways

Architecture Principles

  • Context-driven state management
  • Service layer abstraction
  • Optimistic UI updates
  • Real-time subscriptions
  • Protected routes with auth guards

Development Philosophy

  • Mobile-first design
  • Problem-focused categorization
  • Community-driven engagement
  • University-specific features
  • AI-assisted development workflow

Mental Model Summary

  1. IlliniHunt = Product Hunt for UIUC
  2. Problem-centered categories (not tech-focused)
  3. Real-time voting and comments
  4. Supabase backend with RLS security
  5. React + TypeScript frontend
  6. Optimistic UI with error handling
  7. Context-based state management

layout: center class: text-center

🚀 Ready to Code!

🎓
IlliniHunt Mental Model Complete
You now have the complete mental model for vibe coding on IlliniHunt!
Happy Coding! 🚀