GrantShark Backend Docs

GrantShark's backend is a Python FastAPI application. It connects to Supabase (PostgreSQL), uses Anthropic Claude for essay guidance, integrates with Stripe for billing, and sends emails via Resend. The scholarship scraper runs nightly via a cron job.

Tech Stack

• API Server: Python FastAPI + Uvicorn
• Database: Supabase (PostgreSQL)
• AI: Anthropic Claude via API
• Payments: Stripe
• Email: Resend
• Scheduler: APScheduler (nightly scraper)
• Hosting: Railway.app

Database Schema

CREATE TABLE students (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email TEXT UNIQUE NOT NULL,
  name TEXT, gpa DECIMAL(3,2),
  grad_year INTEGER, major TEXT,
  activities TEXT, essay_sample TEXT,
  stripe_customer_id TEXT,
  plan TEXT DEFAULT 'basic',
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE scholarships (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL, org TEXT,
  amount INTEGER, deadline DATE,
  requirements JSONB, url TEXT,
  scraped_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE applications (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  student_id UUID REFERENCES students(id),
  scholarship_id UUID REFERENCES scholarships(id),
  status TEXT DEFAULT 'matched',
  essay_text TEXT, essay_status TEXT DEFAULT 'pending',
  submitted_at TIMESTAMPTZ, won_at TIMESTAMPTZ,
  won_amount INTEGER
);

API Endpoints

AI Essay Guidance

Essay drafts are generated using Claude. The draft uses the student's profile and provided context. Students review, edit, and approve before any submission. Scholarships prohibiting AI assistance are flagged automatically.

import anthropic

def generate_essay_guidance(student, scholarship):
    client = anthropic.Anthropic()
    message = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1000,
        messages=[{
            "role": "user",
            "content": f"""Write a {scholarship['word_limit']} word scholarship essay draft
for this student to review and personalize:

Student: {student['name']} | GPA: {student['gpa']}
Activities: {student['activities']}
Essay Sample: {student['essay_sample'][:300]}

Scholarship Prompt: "{scholarship['prompt']}"
Organization: {scholarship['org']}

Write in first person. Be specific. Student will edit this draft."""
        }]
    )
    return message.content[0].text

Scholarship Scraper

The scraper runs nightly at 2am UTC via APScheduler. It checks major scholarship databases and stores new entries in Supabase. Matching runs after each new batch.

Email System (Resend)

All transactional emails go through Resend. Templates: welcome, new_matches, essay_ready, submitted, win_notification, fee_invoice, weekly_digest.

Stripe Integration

import stripe
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

def charge_success_fee(student, won_amount, fee_pct=0.05):
    fee = int(won_amount * fee_pct * 100)
    invoice_item = stripe.InvoiceItem.create(
        customer=student["stripe_customer_id"],
        amount=fee, currency="usd",
        description=f"GrantShark success fee ({int(fee_pct*100)}%)"
    )
    invoice = stripe.Invoice.create(
        customer=student["stripe_customer_id"],
        auto_advance=True
    )
    invoice.finalize_invoice()
    return invoice

Deployment Guide

• Push your code to GitHub
• Connect Railway to your GitHub repo
• Add all environment variables in Railway dashboard
• Railway auto-detects Python and runs uvicorn
• Add custom domain: api.grantshark.com

Environment Variables

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_service_role_key
ANTHROPIC_API_KEY=sk-ant-...
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
RESEND_API_KEY=re_...
FRONTEND_URL=https://grantshark.com