Skip to main content

Source: ocean/docs/SYSTEM_ARCHITECTURE.md | ✏️ Edit on GitHub

Ocean Platform System Architecture

Quick Reference: Multi-tenant SaaS with isolated tenant databases, Supabase auth/management, and Edge Functions for business logic.

High-Level Architecture​

Data Architecture​

Authentication Flow​

Multi-Tenant Isolation​

Request Flow Patterns​

Standard API Request​

Stripe Webhook Flow​

Deployment Architecture​

Security Boundaries​

Component Interaction Map​

Development Environment​

Key Design Decisions​

Multi-Tenancy Strategy​

  • Database-per-tenant using Neon for complete isolation
  • Shared authentication via Supabase for simplified management
  • Organization-centric design with clear ownership models

Authentication Architecture​

  • Passwordless OTP only (no passwords to manage)
  • JWT-based with 10-minute OTP expiry for security
  • Fail-closed security model (no fallbacks)

Data Flow​

  • Command Query Separation: Mutations via GraphQL, queries via TanStack Query
  • Centralized auth state with React Context
  • Optimistic updates for better UX

Technology Choices​

  • React 19 with concurrent features
  • TanStack ecosystem for routing, state, and forms
  • Valibot for runtime validation
  • shadcn/ui for consistent design system

Performance Characteristics​

Frontend​

  • Bundle size: ~1MB total, code splitting enabled
  • First paint: <1s on good connections
  • Time to interactive: <2s
  • Core Web Vitals: All green

Backend​

  • Cold start: <100ms (Edge Functions)
  • Database queries: <50ms average
  • GraphQL response: <200ms average
  • Authentication: <100ms JWT validation

Scalability​

  • Tenant databases: Unlimited (Neon auto-scaling)
  • Concurrent users: 1000+ per organization
  • API requests: 100k+ per day supported
  • Storage: Unlimited per tenant database

Monitoring & Observability​

Error Tracking​

  • Sentry: All uncaught errors, performance monitoring
  • Custom logging: Structured logs in Edge Functions
  • Health checks: Automated production monitoring

Analytics​

  • PostHog: User behavior, feature flags, A/B testing
  • Vercel Analytics: Core Web Vitals, page views
  • Custom metrics: Business KPIs via database queries

Performance Monitoring​

  • Bundle analysis: Automated size regression testing
  • Database monitoring: Query performance tracking
  • API monitoring: Response time and error rate tracking