Skip to main content

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

Systematic Maintenance Guide for Ocean Platform

Overview​

This guide provides a systematic approach to maintaining the Ocean platform with just two people. It focuses on automation, clear patterns, and reducing complexity.

🎯 Core Principles​

  1. Automate Everything Possible - If we do it twice, automate it
  2. Enforce Patterns Through Tools - Don't rely on memory
  3. Fail Fast - Catch issues before they reach production
  4. Document by Doing - Scripts are better than guides

🔧 Development System​

One-Command Setup (TO BE IMPLEMENTED)​

# This script should handle EVERYTHING
./scripts/setup-ocean.sh

This should:

  • Check system requirements
  • Install dependencies
  • Set up local Supabase
  • Configure secrets from 1Password/secure store
  • Run initial migrations
  • Seed development data
  • Generate all types
  • Start development environment

Daily Development Commands​

# Start everything (Supabase + codegen + dev)
pnpm dev:full

# Validate before committing (catches 90% of issues)
pnpm validate

# Update all generated code
pnpm codegen:all

# Check bundle impact
pnpm analyze:bundle

Pattern Enforcement Checklist​

1. Creating New Features​

  • Use established patterns (check /docs/patterns/)
  • Keep files under 400 lines
  • Add tests in same PR
  • Update types if needed
  • Check bundle size impact

2. Edge Functions MUST​

// Use the wrapper - NO EXCEPTIONS
import { createEdgeFunction, createStripeFunction } from '../_shared/function-wrapper.ts'

// Regular functions
export default createEdgeFunction(async (req, context) => {
  // Implementation
})

// Stripe functions
export default createStripeFunction(async (req, context) => {
  // Implementation with context.stripe available
})

3. React Hooks MUST​

// Use centralized mutations - NO EXCEPTIONS
import { useMutationWithToast } from '@/hooks/shared/use-mutation-with-toast'

export const useMyFeature = () => {
  return useMutationWithToast({
    mutationFn: async (input) => {
      /* ... */
    },
    successMessage: 'Feature completed!',
    invalidateQueries: [['feature-data']],
  })
}

4. Database Changes MUST​

# 1. Create migration
supabase migration new feature_name

# 2. Apply and test locally
supabase db reset

# 3. Generate types
pnpm codegen:all

# 4. Update GraphQL schema if needed
pnpm codegen:schema

🚨 Red Flags to Watch For​

Code Smells​

  1. File > 400 lines → Split immediately
  2. Duplicate code → Extract to shared
  3. Raw API calls → Use established patterns
  4. Console.log in PR → Use proper logging
  5. Hardcoded values → Move to constants/env

Process Smells​

  1. Manual deployment steps → Automate
  2. "Just this once" exceptions → No exceptions
  3. Undocumented scripts → Add help text
  4. Failing to update types → Add to checklist
  5. Skipping tests → Tests required

📅 Maintenance Schedule​

Daily (Automated)​

  • ✓ Security scanning (pre-commit)
  • ✓ Type checking (CI)
  • ✓ Linting (CI)
  • ✓ Unit tests (CI)

Weekly (Manual Review)​

# Monday Morning Routine
pnpm outdated          # Check dependencies
pnpm audit            # Security check
pnpm test:all         # Full test suite

# Review metrics
- Check Sentry for new errors
- Review bundle size trends
- Check slow query logs

Monthly (Deep Dive)​

  1. Dependency Updates

    • Review Renovate PRs
    • Test major updates locally
    • Update lock files

  2. Performance Audit

    • Analyze slow queries
    • Review bundle size graph
    • Check error rates

  3. Code Quality

    # Find large files
    ./scripts/find-large-files.sh

    # Find duplicates
    ./scripts/find-duplicates.sh

Quarterly (Strategic)​

  1. Pattern Review

    • Are patterns being followed?
    • Do we need new patterns?
    • Remove unused patterns

  2. Automation Audit

    • What are we doing manually?
    • What can be automated?
    • Update scripts

  3. Documentation Sync

    • Update CLAUDE.md
    • Review ADRs
    • Update examples

🛠️ Problem Resolution Flowchart​

Problem Detected
    ↓
Is it documented? → YES → Follow docs
    ↓ NO
Is there a pattern? → YES → Apply pattern
    ↓ NO
Create pattern → Document → Implement

🚀 Deployment System​

Feature Development​

# 1. Create feature branch
git checkout -b feat/new-feature

# 2. Develop with live validation
pnpm dev:full

# 3. Validate completely
pnpm validate
pnpm test:all
pnpm analyze:bundle

# 4. Commit with conventional message
git commit -m "feat: add new feature"

# 5. Push and create PR
git push -u origin feat/new-feature

PR Checklist (Automated)​

  • TypeScript passes
  • ESLint passes
  • Tests pass
  • Bundle size acceptable
  • No secrets exposed
  • Migrations run

Production Deployment​

# Automatic on merge to main
# Rollback if needed
./scripts/rollback-prod.sh <version>

📊 Health Metrics​

Green (Healthy)​

  • Build time < 2 minutes
  • Bundle size increase < 5%
  • Test coverage > 80%
  • Zero TypeScript errors
  • All patterns followed

Yellow (Warning)​

  • Build time 2-5 minutes
  • Bundle size increase 5-10%
  • Test coverage 70-80%
  • TypeScript warnings
  • Some pattern violations

Red (Critical)​

  • Build time > 5 minutes
  • Bundle size increase > 10%
  • Test coverage < 70%
  • TypeScript errors
  • Systematic pattern violations

🔥 Emergency Procedures​

Production Down​

# 1. Check status
./scripts/check-prod-health.sh

# 2. Quick rollback
./scripts/emergency-rollback.sh

# 3. Investigate
./scripts/analyze-crash.sh

Security Breach​

# 1. Rotate all secrets
./scripts/rotate-all-secrets.sh

# 2. Audit access
./scripts/audit-access.sh

# 3. Update dependencies
pnpm update --latest

💡 Efficiency Tips​

1. Use Aliases​

# Add to .zshrc/.bashrc
alias od="pnpm dev:full"
alias ov="pnpm validate"
alias oc="pnpm codegen:all"
alias ot="pnpm test:all"

2. Use Snippets​

Create VS Code snippets for:

  • Edge Function template
  • React Hook template
  • Test file template
  • Migration template

3. Automate Repetitive Tasks​

If you do it twice, script it:

# Example: Create new feature
./scripts/new-feature.sh billing "Add invoice download"
# Creates: branch, files, tests, updates routes

🎯 Success Criteria​

You know the system is working when:

  1. Development is predictable - Same steps every time
  2. Errors caught early - Before commit, not in production
  3. Patterns are natural - Don't have to think about them
  4. Maintenance is routine - Weekly tasks take < 30 minutes
  5. Deployments are boring - Push and forget

📚 Quick Reference​

Must-Have Bookmarks​

Key Commands​

pnpm dev:full          # Start everything
pnpm validate          # Pre-commit check
pnpm codegen:all       # Update types
pnpm analyze:bundle    # Check size
pnpm test:all          # Full test suite

Pattern Files​

  • Edge Functions: /supabase/functions/_shared/function-wrapper.ts
  • React Hooks: /src/hooks/shared/use-mutation-with-toast.ts
  • GraphQL: /supabase/functions/graphql-v2/schema.ts
  • Types: /src/types/database.generated.ts

Remember: The system should work for us, not the other way around. If something feels manual or repetitive, automate it.