Skip to main content

Source: ocean/docs/adr/ADR-036-phase-6-backend-systematization.md | ✏️ Edit on GitHub

ADR-036: Phase 6 Backend Systematization and Code Organization

Status​

Accepted

Context​

The Ocean platform had grown organically with several architectural inconsistencies that were impacting maintainability and security:

  1. Large Files: Four critical files exceeded 400 lines, making them difficult to maintain and navigate
  2. Inconsistent Edge Function Patterns: 11 Edge Functions used different authentication and error handling approaches
  3. Code Duplication: Repeated patterns across functions without proper abstraction
  4. Security Vulnerabilities: Some functions lacked proper authentication despite handling sensitive operations
  5. Mixed Observability: Inconsistent logging and monitoring across services

The codebase had reached a point where systematic refactoring was necessary to maintain development velocity and ensure security.

Decision​

We implemented a comprehensive backend systematization initiative (Phase 6) with the following key decisions:

1. File Size Standardization​

  • Decision: Split all files over 400 lines into focused, modular structures
  • Approach: Create module directories with logical separation of concerns
  • Maintain: Backward compatibility through re-export patterns

2. Edge Function Wrapper Standardization​

  • Decision: All Edge Functions must use standardized wrapper patterns
  • Patterns:
    • createEdgeFunction - Authenticated operations (4 functions)
    • createStripeFunction - Stripe integrations (6 functions)
    • createWebhookFunction - Webhook handling (1 function)
    • createGraphQLFunction - GraphQL services (1 function)
  • Eliminated: createPublicFunction for sensitive operations

3. Security Hardening​

  • Decision: All sensitive operations require proper authentication
  • Approach: Replace manual authentication checks with wrapper-enforced auth
  • Access Control: Implement consistent role-based access (owner/admin)

4. Code Quality Standards​

  • Decision: Maintain zero TypeScript errors and ESLint warnings
  • Cleanup: Remove unused imports, duplicate code, and console.log statements
  • Consistency: Standardize logging patterns across all functions

Implementation​

Files Modularized​

  1. use-sentry-breadcrumbs.ts (471 lines → 8 focused modules)

    • Separated by concern: navigation, UI, API, user-state, performance, business
    • Maintained single import point for consumers

  2. sentry-distributed-tracing.ts (452 lines → 8 focused modules)

    • Logical separation: headers, fetch, GraphQL, WebSocket, Supabase, TanStack Query
    • Preserved backward compatibility with legacy exports

  3. GraphQL-client.ts (446 lines → 8 focused modules)

    • Clear separation: client, errors, validation, fragments, operations
    • Used by 17+ files across codebase without breaking changes

  4. provision-tenant-resources/index.ts (423 lines → 124 lines + helpers)

    • Extracted: Neon operations, GraphQL setup, provisioning logic
    • 70% reduction in main file complexity

Edge Function Standardization​

  • Before: Mixed patterns, manual auth, inconsistent error handling
  • After: 100% consistent wrapper usage across all 11 functions
  • Security: Fixed 1 critical vulnerability, upgraded 2 functions to proper auth

New Infrastructure​

  • createGraphQLFunction: Custom wrapper for GraphQL Yoga integration
  • Enhanced Observability: Request tracking, performance monitoring, Sentry integration
  • Standardized CORS: Consistent cross-origin handling

Consequences​

Positive​

  1. Security: Eliminated authentication vulnerabilities, consistent access control
  2. Maintainability: Smaller, focused modules easier to understand and modify
  3. Developer Experience: Predictable patterns, better error messages, clear structure
  4. Code Quality: Zero compilation errors, zero linting warnings
  5. Observability: Complete request tracing and performance monitoring
  6. Scalability: Modular architecture supports future growth

Negative​

  1. File Count: Increased from ~15 to ~40 files (manageable with better organization)
  2. Learning Curve: Developers need to understand wrapper patterns (well-documented)
  3. Migration Effort: Required systematic refactoring (completed successfully)

Neutral​

  1. Backward Compatibility: All existing imports continue to work unchanged
  2. Performance: No measurable impact on runtime performance
  3. Bundle Size: Minimal impact due to tree-shaking

Measurements​

  • Files Under 400 Lines: 4/4 targets achieved (100%)
  • Edge Function Consistency: 11/11 functions using proper wrappers (100%)
  • Security Coverage: 0 unauthenticated sensitive operations (was 1)
  • Code Quality: 0 TypeScript errors, 0 ESLint warnings
  • Lines Refactored: ~1,800 lines moved to focused modules

Alternatives Considered​

  1. Gradual Refactoring: Rejected due to inconsistency risks
  2. Different File Size Limits: 400 lines chosen based on cognitive load research
  3. Microservices Split: Rejected as premature for current scale
  4. Monorepo Structure: Considered but current structure works well
  • ADR-028: Local testing environment setup
  • ADR-014: Cloud-first testing strategy
  • ADR-005: Supabase JWT authentication
  • ADR-035: Atomic provisioning pattern

Notes​

This represents the largest systematic refactoring of the Ocean platform to date. The work establishes architectural patterns that will guide development for the foreseeable future. All changes maintain backward compatibility while significantly improving code quality, security, and maintainability.

The systematization creates a solid foundation for Phase 7 (UI completion) and Phase 8 (advanced features) development.