Skip to main content

Source: ocean/docs/adr/ADR-043-developer-experience-automation.md | ✏️ Edit on GitHub

ADR-043: Developer Experience Automation and Performance Monitoring

Status​

Accepted

Context​

After completing phases 1-4 of our comprehensive refactoring project, we identified the need for developer experience improvements to prevent future code drift and maintain system quality. The key challenges were:

  1. Schema Drift Prevention: Manual maintenance of GraphQL schemas led to drift between database and API definitions
  2. Bundle Size Regression: No automated monitoring of bundle size increases
  3. Performance Visibility: Lack of insight into Edge Function and database query performance
  4. Code Generation Friction: Multiple manual steps required to keep generated code in sync

Decision​

We implemented Phase 5 of the refactoring project, focusing on automation and monitoring tools that improve developer productivity and prevent regressions.

1. Database-to-GraphQL Schema Generation​

Created an automated tool that generates GraphQL schema from database migrations:

// tools/generate-graphql-schema.ts
- Parses all migration files in order
- Extracts table and column definitions
- Generates corresponding GraphQL types
- Maps PostgreSQL types to GraphQL types
- Creates Query and Mutation definitions

2. Bundle Size Analysis Automation​

Implemented automated bundle size tracking and reporting:

// tools/analyze-bundle.ts
- Builds production bundle
- Analyzes chunk sizes (both raw and gzipped)
- Compares against previous builds
- Generates detailed reports
- Warns on significant size increases (>5%)
- Fails CI on critical increases (>10%)

3. Performance Tracking Infrastructure​

Added comprehensive performance monitoring to Edge Functions:

// supabase/functions/_shared/performance-tracking.ts
- Tracks operation duration
- Monitors database query performance
- Identifies slow queries (>1s warning, >5s critical)
- Creates tracked Supabase client proxy
- Batches metrics for efficient reporting

4. Automated Code Generation Scripts​

Enhanced package.json with developer-friendly scripts:

{
  "scripts": {
    "codegen:database": "Generate TypeScript types from database",
    "codegen:graphql": "Generate GraphQL types and hooks",
    "codegen:schema": "Generate GraphQL schema from migrations",
    "codegen:all": "Run all code generation",
    "dev:full": "Start Supabase + watch codegen + dev server",
    "analyze:bundle": "Analyze and report bundle size"
  }
}

5. CI/CD Integration​

Updated GitHub Actions to include bundle analysis:

- name: Analyze bundle size
  run: pnpm run analyze:bundle:ci

- name: Comment bundle analysis on PR
  uses: actions/github-script@v7
  # Posts/updates bundle size report as PR comment

Implementation Details​

Performance Tracking Integration​

The performance tracking seamlessly integrates with our Edge Function wrapper pattern:

// Automatic tracking for all Edge Functions
return await withPerformanceTracking(
  `${req.method} ${new URL(req.url).pathname}`,
  () => handler(req, context),
  { requestId, userId, organizationId }
)

// Tracked Supabase client for query monitoring
const supabase = createTrackedSupabaseClient(baseSupabase)

Bundle Analysis Thresholds​

  • Warning: 5% increase - PR comment with warning
  • Error: 10% increase - CI fails, requires review
  • Success: >5% decrease - Congratulatory message

Schema Generation Safety​

The schema generator:

  • Preserves snake_case naming convention
  • Skips system tables (prefixed with _)
  • Handles ALTER TABLE statements
  • Generates both queries and mutations
  • Includes proper nullability based on database constraints

Consequences​

Positive​

  • Prevented Schema Drift: Database changes automatically reflected in GraphQL
  • Bundle Size Visibility: Every PR shows bundle impact
  • Performance Insights: Slow queries identified immediately
  • Developer Velocity: Single command to update all generated code
  • Quality Gates: Automated checks prevent regressions

Negative​

  • Build Time: Bundle analysis adds ~30s to CI
  • Learning Curve: Developers need to understand new tools
  • Maintenance: Additional tools to maintain

Metrics​

  • Schema Drift: Reduced to zero (automated generation)
  • Bundle Size Regressions: Caught before merge
  • Slow Query Detection: <1s to identify performance issues
  • Code Generation Time: 5 manual steps → 1 command

Lessons Learned​

  1. Automation Prevents Drift: Manual processes inevitably lead to inconsistencies
  2. Visibility Drives Quality: Making metrics visible improves them
  3. Developer Experience Matters: Good tooling increases productivity
  4. Performance Monitoring: Must be automatic, not opt-in

Future Improvements​

  1. Advanced Bundle Analysis:

    • Tree-shaking effectiveness reports
    • Duplicate dependency detection
    • Chunk splitting recommendations

  2. Performance Dashboards:

    • Real-time performance dashboards
    • Historical trend analysis
    • Automated performance regression alerts

  3. Schema Evolution:

    • Migration impact analysis
    • Breaking change detection
    • Automated compatibility testing

  4. Developer Metrics:

    • Build time tracking
    • Test execution metrics
    • Development velocity insights
  • ADR-037: Comprehensive Code Deduplication Refactoring
  • ADR-038: Edge Function Wrapper Pattern
  • ADR-039: GraphQL Snake Case Standardization
  • ADR-040: React Hook Mutation Pattern
  • ADR-041: Testing Strategy Enhancement
  • ADR-042: Supabase Development Best Practices