Shared Code Extraction Strategy

Overview

This document outlines the strategy for extracting shared types and utilities from the monorepo into reusable packages. Based on the investigation findings, both fundraising and admin functionality already exist within apps/storefront, making this a code organization and reusability initiative rather than a migration from external repositories.

Goal: Create shared packages (@jose-madrid/shared-types and @jose-madrid/shared-utils) that can be consumed by current and future applications in the monorepo, reducing duplication and improving maintainability.

Current State Analysis

Existing Applications

• apps/storefront: Next.js application containing storefront, fundraising, and admin functionality
• apps/backend: API service for backend operations

Code Organization

All business logic currently resides in apps/storefront:

• 107+ fundraising files: Components, types, utilities, API routes
• 415+ admin files: Comprehensive admin interface with RBAC
• Shared types: Currently duplicated or tightly coupled to storefront
• Shared utilities: Reusable logic that could benefit multiple apps

Identified Shared Code

1. Shared Types (packages/shared-types)

Core Business Types

Priority: HIGH - Foundation for all apps

• User & Authentication

  • UserRole enum (ADMIN, DEVELOPER, STAFF, WHOLESALE, FUNDRAISER, CUSTOMER)
  • User interface (base user properties)
  • Session type (authentication session data)
  • Permission types (RBAC permission structure)

• E-Commerce

  • Product interface (product catalog)
  • Order interface (order structure)
  • OrderItem interface (order line items)
  • Category interface (product categories)
  • CartItem interface (shopping cart items)
  • PaymentMethod type (payment method options)
  • ShippingMethod type (shipping options)

• Fundraising

  • Fundraiser interface (campaign structure)
  • FundraiserParticipant interface (participant data)
  • FundraiserCharacter interface (Battle Arena characters)
  • FundraiserTeam interface (team structure)
  • BattleState interface (Battle Arena state)
  • CharacterClass type (character class enum)
  • CommissionRate type (commission calculation)

• Email & Communications

  • NewsletterTemplate type (email templates)
  • NewsletterBlock type (email blocks)
  • EmailCampaign interface (campaign structure)
  • EmailAutomation interface (automation workflows)

• Analytics

  • AnalyticsMetric interface (metric structure)
  • ChartData interface (chart data format)
  • DateRange interface (analytics date ranges)

API Response Types

Priority: HIGH - Critical for API consistency

• ApiResponse<T> generic (standardized API responses)
• ApiError interface (error structure)
• PaginatedResponse<T> generic (paginated results)
• ValidationError interface (validation errors)

Form & Validation Types

Priority: MEDIUM - Developer productivity

• FormField interface (form field structure)
• ValidationSchema type (Zod schema types)
• FormState type (form state management)

2. Shared Utilities (packages/shared-utils)

Authentication & Authorization

Priority: HIGH - Security critical

• RBAC Utilities

  • getUserPermissions(user) - Get user permissions
  • hasPermission(user, permission) - Check permission
  • requirePermission(user, permission) - Assert permission
  • filterByPermissions(items, user) - Filter by permissions

• Role Utilities

  • getRoleBadgeVariant(role) - Get UI badge variant for role
  • formatUserRole(role) - Format role for display
  • isAdmin(user) - Check admin role
  • isDeveloper(user) - Check developer role
  • isStaff(user) - Check staff role

Business Logic

Priority: HIGH - Core calculations

• Fundraising Utilities (apps/storefront/lib/fundraising/)

  • calculateCommission(orderTotal, rate) - Commission calculation
  • calculateCommissionFromNumber(total, rate) - Number version
  • calculateTotalCommission(orders, rate) - Total commission
  • Referral tracking utilities (from referral-tracker.ts)

• Discount & Pricing

  • Discount calculation logic (from lib/discounts.ts)
  • Price formatting utilities

API & Validation

Priority: HIGH - Consistency

• API Helpers (lib/api/)

  • apiResponse<T>(data) - Create success response
  • apiError(message, code) - Create error response
  • validateApiKey(key) - API key validation
  • Rate limiting utilities (from lib/rate-limiter.ts)

• Validation Utilities (lib/validation.ts, lib/validations/)

  • Common Zod schemas (email, phone, etc.)
  • Validation helpers
  • Input sanitization

Data Formatting

Priority: MEDIUM - User experience

• Date & Time

  • Date range utilities (lib/analytics/date-range.ts)
  • Date formatting helpers

• Number & Currency

  • Currency formatting
  • Number formatting
  • Percentage calculations

• String Utilities

  • Slug generation
  • Truncation
  • Sanitization

Analytics

Priority: MEDIUM - Reporting

• Chart Utilities (lib/analytics/chart-utils.ts)
  • Chart data transformation
  • Metric calculations
  • Data aggregation helpers

Crypto & Security

Priority: HIGH - Security critical

• Crypto Utilities (lib/crypto.ts)
  • Hashing utilities
  • Token generation
  • Encryption/decryption helpers

3. Audit Log Utilities

Priority: MEDIUM - Compliance

• Audit logging (lib/audit.ts)
• Event tracking
• Change history

Proposed Package Structure

packages/
├── shared-types/
│   ├── package.json
│   ├── tsconfig.json
│   ├── index.ts                    # Main export
│   ├── src/
│   │   ├── user.ts                # User & auth types
│   │   ├── ecommerce.ts           # Product, order types
│   │   ├── fundraising.ts         # Fundraiser types
│   │   ├── email.ts               # Email types
│   │   ├── analytics.ts           # Analytics types
│   │   ├── api.ts                 # API response types
│   │   └── forms.ts               # Form types
│   └── README.md
│
└── shared-utils/
    ├── package.json
    ├── tsconfig.json
    ├── index.ts                    # Main export
    ├── src/
    │   ├── auth/
    │   │   ├── rbac.ts            # RBAC utilities
    │   │   └── roles.ts           # Role utilities
    │   ├── fundraising/
    │   │   ├── commission.ts      # Commission calculations
    │   │   └── referrals.ts       # Referral tracking
    │   ├── api/
    │   │   ├── responses.ts       # API response helpers
    │   │   ├── validation.ts      # API validation
    │   │   └── rate-limit.ts      # Rate limiting
    │   ├── formatting/
    │   │   ├── currency.ts        # Currency formatting
    │   │   ├── date.ts            # Date formatting
    │   │   └── string.ts          # String utilities
    │   ├── analytics/
    │   │   └── charts.ts          # Chart utilities
    │   ├── crypto/
    │   │   └── index.ts           # Crypto utilities
    │   └── validation/
    │       ├── schemas.ts         # Common Zod schemas
    │       └── helpers.ts         # Validation helpers
    └── README.md

Migration Order (Phased Approach)

To minimize breaking changes and ensure stability, extract shared code in the following order:

Phase 1: Foundation Types (Low Risk)

Target: Week 1

1. Create packages/shared-types package

   • Set up package.json with @jose-madrid/shared-types
   • Configure TypeScript for type-only exports
   • Add to workspace

2. Extract Core Types (no dependencies)

   • User & role types
   • API response types (ApiResponse<T>, ApiError)
   • Basic e-commerce types (Product, Order)

3. Update apps/storefront imports

   • Replace local type imports with @jose-madrid/shared-types
   • Verify type-check passes: npm run type-check --workspace=@jose-madrid/storefront

Success Criteria:

• Type-check passes for all apps
• No runtime errors
• Reduced type duplication

Phase 2: Business Types (Medium Risk)

Target: Week 1-2

1. Extract Fundraising Types

   • Fundraiser, FundraiserParticipant, FundraiserTeam
   • FundraiserCharacter, BattleState, CharacterClass

2. Extract Email Types

   • NewsletterTemplate, NewsletterBlock
   • Email campaign types

3. Extract Analytics Types

   • Chart data types
   • Metric types

Success Criteria:

• All apps type-check successfully
• Tests pass
• No compilation errors

Phase 3: Utility Functions - Pure Logic (Low Risk)

Target: Week 2

1. Create packages/shared-utils package

   • Set up package.json with @jose-madrid/shared-utils
   • Configure TypeScript for code exports
   • Add to workspace

2. Extract Pure Calculation Functions (no external dependencies)

   • calculateCommission() and related functions
   • Currency/number formatting
   • String utilities (slug, truncate)

3. Update storefront imports

   • Replace local utility imports
   • Verify unit tests pass

Success Criteria:

• All utility tests pass
• No side effects from extraction
• Clean import paths

Phase 4: API & Validation Utilities (Medium Risk)

Target: Week 2-3

1. Extract API Helpers

   • Response builders (apiResponse, apiError)
   • API key validation
   • Rate limiting utilities

2. Extract Validation Utilities

   • Common Zod schemas
   • Validation helpers

3. Update all apps

   • Storefront
   • Backend (if applicable)

Success Criteria:

• API responses maintain format
• Validation works correctly
• Rate limiting functions correctly

Phase 5: Authentication Utilities (Higher Risk)

Target: Week 3

1. Extract RBAC Utilities (carefully - security critical)

   • Permission checking functions
   • Role utilities
   • Navigation filtering

2. Extensive Testing

   • Unit tests for RBAC functions
   • Integration tests for permission flows
   • Manual testing of admin access

3. Update storefront

   • Replace RBAC imports
   • Verify all permission checks work

Success Criteria:

• All permission checks work correctly
• No security regressions
• Admin access remains restricted
• Tests cover edge cases

Phase 6: Analytics & Crypto (Low-Medium Risk)

Target: Week 3-4

1. Extract Chart Utilities

   • Chart data transformation
   • Metric calculations

2. Extract Crypto Utilities

   • Hashing, token generation
   • IMPORTANT: Verify crypto compatibility across Node versions

3. Extract Audit Utilities

   • Audit logging helpers

Success Criteria:

• Analytics display correctly
• Crypto functions work identically
• Audit logs continue to work

Breaking Change Prevention Strategy

1. Incremental Extraction

• Extract one category at a time
• Run full test suite after each extraction
• Commit after each successful phase

2. Parallel Development

• Keep original code in place during extraction
• Only remove original code after successful verification
• Use deprecation comments if needed

3. Type Safety

• Leverage TypeScript for compile-time safety
• Run npm run type-check after every change
• Use strict TypeScript config in shared packages

4. Testing Strategy

• Unit Tests: Test shared utilities in isolation
• Integration Tests: Verify apps work with shared code
• E2E Tests: Run fundraising and admin E2E tests
• Manual Testing: Test critical flows (checkout, permissions, fundraising)

5. Version Control

• One pull request per phase
• Detailed commit messages
• Easy to revert if issues arise

Dependency Management

Package Dependencies

shared-types:

{
  "dependencies": {},
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

shared-utils:

{
  "dependencies": {
    "@jose-madrid/shared-types": "workspace:*",
    "@prisma/client": "^5.0.0",  // For Decimal type
    "zod": "^3.0.0"               // For validation schemas
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "vitest": "^1.0.0"            // For testing
  }
}

Import Conventions

// ✅ CORRECT: Named imports from shared packages
import { UserRole, Fundraiser } from '@jose-madrid/shared-types'
import { calculateCommission, hasPermission } from '@jose-madrid/shared-utils'

// ❌ AVOID: Deep imports (breaks encapsulation)
import { UserRole } from '@jose-madrid/shared-types/src/user'

Testing Requirements

Phase 1-2 (Types)

• Type-check passes: npm run type-check
• Build succeeds: turbo run build

Phase 3-6 (Utilities)

• Unit tests for all extracted utilities
• Integration tests for critical paths
• Minimum 80% code coverage for shared packages

E2E Testing

Run after each phase:

# Fundraising flow
npm run test:e2e --workspace=@jose-madrid/storefront -- fundraising

# Admin access and permissions
npm run test:e2e --workspace=@jose-madrid/storefront -- admin

# Checkout flow (tests commission calculations)
npm run test:e2e --workspace=@jose-madrid/storefront -- checkout

Rollback Strategy

If issues arise during any phase:

1. Immediate Rollback: Revert the last commit
2. Identify Root Cause: Debug the issue
3. Fix Forward: Apply fix and re-test
4. Document: Add to "Known Issues" section

Each phase is independently revertible without affecting previous phases.

Success Metrics

Quantitative

• Code Reduction: 20-30% reduction in duplicated code
• Type Coverage: 100% of core business types in shared packages
• Test Coverage: 80%+ for shared utilities
• Build Time: No significant increase in build time
• Bundle Size: No increase in bundle size (tree-shaking verified)

Qualitative

• Developer Experience: Easier to find and reuse types/utilities
• Consistency: Single source of truth for business logic
• Maintainability: Changes to shared logic update all apps
• Type Safety: Better autocomplete and type inference

Risk Assessment

Low Risk

• Pure type extraction (Phase 1-2)
• Pure calculation functions (Phase 3)
• Analytics utilities (Phase 6)

Medium Risk

• API & validation utilities (Phase 4)
• Chart utilities (Phase 6)

Higher Risk

• RBAC utilities (Phase 5) - Security critical
• Crypto utilities (Phase 6) - Compatibility critical

Mitigation:

• Extensive testing for higher-risk items
• Security review for RBAC extraction
• Backward compatibility checks for crypto

Future Considerations

When External Apps Are Added (apps/fundraising, apps/admin)

If/when fundraising or admin are extracted into separate apps:

1. Immediate Benefit: Shared packages already exist
2. Reduced Duplication: New apps import from shared packages
3. Consistent Logic: Business rules centralized
4. Easier Migration: Types already defined

Package Versioning

Once extracted:

• Use workspace protocol: "@jose-madrid/shared-types": "workspace:*"
• Lock shared package versions for production deployments
• Consider semantic versioning for breaking changes

Documentation

Each shared package should include:

• README.md: Package purpose, usage examples
• CHANGELOG.md: Version history
• API Documentation: Generated from TSDoc comments

Timeline Summary

Total Estimated Time: 3-4 weeks for complete extraction

Recommendation: Start with Phases 1-3 as a proof of concept (Week 1-2), then evaluate before continuing.

Open Questions

1. ❓ Should we extract utilities that depend on Prisma (e.g., getPrisma() from auth.ts)?

   • Recommendation: Keep Prisma-dependent code in apps for now, extract only pure logic

2. ❓ Should email template utilities be shared or remain in storefront?

   • Recommendation: Extract types, keep rendering logic in storefront initially

3. ❓ Should we create additional packages (e.g., shared-config, shared-constants)?

   • Recommendation: Start with types and utils, add more packages based on actual need

4. ❓ How to handle environment-specific code (e.g., different API URLs)?

   • Recommendation: Keep env-specific code in apps, shared packages should be env-agnostic

Next Steps

1. Review this strategy with team/stakeholders
2. Create Phase 1 implementation subtask (foundation types)
3. Set up CI checks for shared packages (type-check, test, lint)
4. Begin Phase 1 extraction following the migration order above

Document Version: 1.0
Last Updated: 2026-06-19
Author: Claude (Subtask 1-4)