Skip to main content

​
FindU Architecture

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

​
System Overview

​
Repository Structure

Each component lives in its own repository:

ios_app

Purpose: Native iOS application for students
  • SwiftUI interface
  • Supabase SDK integration
  • Real-time messaging
  • Apple/Google auth

web_app

Purpose: Partner & staff web dashboard
  • React 19 + TypeScript
  • Partner portal features
  • Internal admin tools
  • Analytics & reporting

matching-algorithm

Purpose: ML-powered matching engine
  • Python FastAPI service
  • Student-school matching
  • Recommendation engine
  • Hosted on Railway

data_scraping

Purpose: Data collection scripts
  • College Scorecard sync
  • Image scraping
  • AI-powered data enrichment
  • Railway scheduled jobs

docs

Purpose: This documentation site
  • Mintlify framework
  • API references
  • Developer guides
  • Architecture docs

​
Data Flow

​
1. Student Matching Flow

​
2. Partner Management Flow

​
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
Both environments use the same Supabase instance. Always use test accounts (emails containing ‘test’) when developing to avoid affecting real users.

​
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

​
Deployment Pipeline

All repositories follow a consistent dev/main deployment pattern:

​
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

Developer Setup

Get your local environment running

Repository Guide

Learn when to work in which repo