Skip to main content

​
Partner Dashboard API Vision

This document outlines a potential future API design for partner features. Currently, the partner dashboard communicates directly with Supabase.
This is a design reference document. These endpoints do not currently exist. The partner dashboard uses Supabase SDK for all operations.

​
Current Implementation

The partner dashboard currently:
  • Uses Supabase JavaScript SDK
  • Implements Row Level Security (RLS) for permissions
  • Queries database tables directly
  • Handles real-time subscriptions via Supabase
// Current approach
const { data: students } = await supabase
  .from('student_school_interactions')
  .select('*, students(*)')
  .eq('school_id', currentSchoolId)
  .order('created_at', { ascending: false });

​
Future API Benefits

A dedicated Partner API could provide:

​
1. Simplified Analytics

Instead of complex joins: 
// Future API approach
const analytics = await api.get('/partner/analytics', {
  period: '30d',
  metrics: ['engagement', 'geography', 'quality']
});

​
2. Batch Operations

Enable bulk messaging and actions: 
// Send message to multiple students
await api.post('/partner/messages/bulk', {
  studentIds: selectedStudents,
  template: 'scholarship_reminder',
  personalize: true
});

​
3. Aggregated Data

Pre-computed metrics and insights: 
// Get campaign performance
const campaign = await api.get('/partner/campaigns/current', {
  include: ['demographics', 'engagement_funnel', 'top_interests']
});

​
Proposed Endpoint Structure

​
Analytics & Reporting

GET  /partner/analytics/overview
GET  /partner/analytics/students
GET  /partner/analytics/engagement
GET  /partner/analytics/geographic
POST /partner/analytics/export

​
Student Management

GET  /partner/students
GET  /partner/students/:id
GET  /partner/students/:id/interactions
POST /partner/students/filter
GET  /partner/campaigns/:id/students

​
Messaging

GET  /partner/conversations
GET  /partner/conversations/:id/messages
POST /partner/messages
POST /partner/messages/bulk
POST /partner/messages/templates

​
Profile & Content

GET  /partner/profile
PATCH /partner/profile
POST /partner/profile/sections
POST /partner/media/upload
DELETE /partner/media/:id

​
Scholarships

GET  /partner/scholarships
POST /partner/scholarships
PATCH /partner/scholarships/:id
GET  /partner/scholarships/:id/analytics
POST /partner/scholarships/:id/archive

​
Team Management

GET  /partner/team/members
POST /partner/team/invite
PATCH /partner/team/members/:id
DELETE /partner/team/members/:id
GET  /partner/team/permissions

​
Design Patterns

​
Permission Scoping

// Middleware to handle entity permissions
async function checkEntityAccess(req: Request) {
  const entityId = req.headers['x-entity-id'];
  const userId = req.user.id;
  
  const hasAccess = await checkUserEntityPermission(userId, entityId);
  if (!hasAccess) {
    throw new ForbiddenError('No access to this entity');
  }
}

​
Response Enrichment

// Enrich student data with computed fields
interface EnrichedStudent {
  id: string;
  profile: StudentProfile;
  interaction: {
    type: 'view' | 'like' | 'dislike';
    date: Date;
    matchScore: number;
    matchGrade: string;
  };
  insights: {
    engagementLevel: 'high' | 'medium' | 'low';
    responseRate: number;
    interests: string[];
  };
}

​
Webhook Events

Partners could subscribe to events: 
interface WebhookEvent {
  event: 'student.liked' | 'message.received' | 'scholarship.saved';
  timestamp: Date;
  data: {
    studentId: string;
    entityId: string;
    metadata: Record<string, any>;
  };
}

​
Implementation Considerations

​
Performance Optimization

  • Cache frequently accessed data (analytics, school profiles)
  • Use database views for complex queries
  • Implement pagination for large datasets
  • Queue bulk operations

​
Security

  • Entity-based access control
  • Rate limiting per organization
  • Audit logging for all actions
  • Input validation and sanitization

​
Developer Experience

  • TypeScript SDK with full type safety
  • Comprehensive error messages
  • Request/response examples
  • Interactive API documentation

​
Migration Path

If implementing this API:
  1. Phase 1: Create read-only endpoints
    • Analytics and reporting
    • Student lists and profiles
  2. Phase 2: Add write operations
    • Messaging
    • Profile updates
    • Scholarship management
  3. Phase 3: Advanced features
    • Webhooks
    • Bulk operations
    • Custom integrations

​
Current Alternative

For now, partners can achieve similar functionality using:
  • Supabase RPC functions for complex queries
  • Database views for aggregated data
  • Edge Functions for custom logic
  • Real-time subscriptions for live updates
See Web App Architecture for current implementation details.