Enterprise Implementation Guide

Enterprise Implementation Guide

Scaling TDI2 to Large React Teams

Transform your enterprise React application from props hell to service-oriented architecture with minimal disruption and maximum team productivity.

🎯 Enterprise Benefits

• 90% Reduction - Components with 5+ props
• 50% Faster - Test setup and execution
• 25% Faster - Feature development velocity
• Zero Conflicts - Teams work independently on services

---

Target Profile: Enterprise React Teams

Team Characteristics

• 10+ developers working on single React application
• Multiple feature teams working in parallel
• Complex business logic requiring clear boundaries
• Props hell - Components with 15+ props
• Testing complexity from mocking component props

Current Pain Points TDI2 Solves

• Props explosion - Components with excessive props → Service injection
• Merge conflicts - Teams stepping on each other’s components → Service boundaries
• Testing hell - Mocking dozens of props for each test → @DiTest/@MockBean
• Inconsistent patterns - Each team invents own state management → Standardized @Service pattern
• Refactoring paralysis - Moving components breaks prop chains → Loose coupling via interfaces
• Environment configuration - Scattered config logic → @Profile management
• Manual lifecycle - Component lifecycle complexity → @PostConstruct/@PreDestroy

---

4-Phase Implementation Strategy

Phase 1: Foundation (Weeks 1-2)

Goal: Establish TDI2 infrastructure without disrupting development

Week 1: Complete Infrastructure Setup

# Install complete TDI2 toolchain (all features production-ready)
npm install @tdi2/di-core @tdi2/vite-plugin-di @tdi2/di-testing valtio

vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { diEnhancedPlugin } from '@tdi2/vite-plugin-di';

export default defineConfig({
  plugins: [
    diEnhancedPlugin({
      enableInterfaceResolution: true,
      enableFunctionalDI: true,
      enableLifecycleHooks: true,
      enableProfileSupport: true,
      enableConfigurationSupport: true,
      enableTestingSupport: true,
      verbose: true,
      generateDebugFiles: process.env.NODE_ENV === 'development'
    }),
    react(),
  ],
});

Enterprise Project Structure

src/
├── services/
│   ├── interfaces/       # Service contracts (team boundaries)
│   ├── implementations/  # Service implementations
│   ├── configurations/   # @Configuration classes
│   └── __tests__/       # Service unit tests with @DiTest
├── repositories/
│   ├── interfaces/       # Data access contracts
│   └── implementations/  # API/Mock implementations with @Profile
├── components/          # Pure presentation components
├── testing/             # @MockBean and test utilities
└── types/               # Shared TypeScript types

Week 2: Team Training

• Architecture workshop (4 hours) - Service-oriented principles
• Hands-on coding (4 hours) - Create first e-commerce service together
• Coding standards - Service naming, interface design, testing requirements

Phase 2: Pilot Implementation (Weeks 3-6)

Goal: Validate TDI2 with one high-value feature

Choose Pilot Feature: E-Commerce Product Catalog

Before: Props Hell

function ProductCatalog({
  products, categories, loading, error, user, cart,
  searchQuery, filters, sortBy, pagination, theme,
  onSearch, onFilter, onSort, onAddToCart, onCategoryChange,
  // ...15+ more props
}: ProductCatalogProps) {
  // 200+ lines of complex state coordination
}

After: Pure Template

function ProductCatalog({
  productService,
  cartService
}: {
  productService: Inject<ProductServiceInterface>;
  cartService: Inject<CartServiceInterface>;
}) {
  const { products, loading, searchQuery } = productService.state;

  return (
    <div className="product-catalog">
      <ProductSearch />
      <ProductFilters />
      <ProductGrid />
    </div>
  );
}

Implementation Schedule

• Week 3: Create product service interfaces and implementations
• Week 4: Transform catalog components to use services
• Week 5: Implement cart service integration
• Week 6: Complete testing and performance validation

Phase 3: Team Expansion (Weeks 7-10)

Goal: Scale TDI2 across multiple feature teams

Service Ownership Model

// Team A: Product Team
interface ProductServiceInterface {
  loadProducts(): Promise<void>;
  searchProducts(query: string): void;
  filterByCategory(category: string): void;
}

// Team B: User Team
interface UserServiceInterface {
  getCurrentUser(): User | null;
  updateProfile(data: ProfileData): Promise<void>;
  getOrderHistory(): Promise<Order[]>;
}

// Infrastructure Team: Shared Services
interface AppStateServiceInterface {
  theme: 'light' | 'dark';
  setTheme(theme: 'light' | 'dark'): void;
  showNotification(message: string): void;
}

Cross-Team Communication Patterns

Service Dependencies:

@Service()
export class CheckoutService {
  constructor(
    @Inject() private userService: UserServiceInterface,    // Team B
    @Inject() private cartService: CartServiceInterface,    // Team A
    @Inject() private paymentService: PaymentServiceInterface  // Team C
  ) {}

  async processCheckout(): Promise<void> {
    const user = this.userService.getCurrentUser();
    const items = this.cartService.getItems();
    // Process checkout with clear team boundaries
  }
}

Phase 4: Full Adoption (Weeks 11-16)

Goal: Complete transformation to service-oriented architecture

Systematic Migration Priority

1. High-value features with worst props hell
2. Leaf components first to avoid dependency issues
3. Shared components last to minimize team conflicts
4. Legacy integration using adapter pattern

---

Team Organization Patterns

Service Ownership Matrix

Team	Owned Services	Shared Dependencies
Product Team	ProductService, CategoryService, InventoryService	AppStateService, CartService
User Team	UserService, ProfileService, AuthService	AppStateService, NotificationService
Order Team	CheckoutService, PaymentService, ShippingService	UserService, ProductService
Infrastructure	AppStateService, NotificationService, LoggingService	All teams consume

Cross-Team Service Communication

@Service()
export class OrderService {
  async createOrder(items: CartItem[]): Promise<void> {
    // Validate with Product Team service
    const validatedItems = await this.productService.validateItems(items);

    // Get user from User Team service
    const user = this.userService.getCurrentUser();

    // Create order with validated data
    const order = await this.orderRepository.createOrder({
      userId: user.id,
      items: validatedItems,
      total: this.calculateTotal(validatedItems)
    });

    // Notify Infrastructure Team service
    this.notificationService.showSuccess(`Order ${order.id} created!`);
  }
}

---

Quality Assurance Standards

Code Review Requirements

1. Service Interface Review - Interfaces reviewed by architecture team
2. Component Purity - Components must be pure templates only
3. Testing Coverage - 90%+ test coverage for services

Automated Quality Gates

// ESLint rules for TDI2 compliance
module.exports = {
  rules: {
    '@tdi2/no-business-logic-in-components': 'error',
    '@tdi2/require-service-interfaces': 'error',
    '@tdi2/no-direct-service-imports': 'error',
    '@tdi2/prefer-service-injection': 'error'
  }
};

Architecture Decision Records

• ADR-001: Service Interface Design Patterns
• ADR-002: Cross-Team Service Communication
• ADR-003: Testing Strategy for Service Architecture
• ADR-004: Error Handling and Performance Monitoring

---

Performance and Monitoring

Key Metrics to Track

1. Bundle Size - Target 15-20kb reduction (eliminate Redux/Context boilerplate)
2. Component Re-renders - Monitor with React DevTools
3. Service Performance - Track method execution times
4. Developer Velocity - Story points per sprint improvement

Monitoring Setup

@Service()
export class ProductService {
  @Trace('ProductService.loadProducts')
  async loadProducts(): Promise<void> {
    const span = trace.getActiveSpan();

    try {
      this.state.loading = true;
      this.state.products = await this.productRepository.getProducts();
      span?.setStatus({ code: SpanStatusCode.OK });
    } catch (error) {
      span?.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
      throw error;
    } finally {
      this.state.loading = false;
    }
  }
}

---

Risk Mitigation

Technical Risks

• Learning Curve → Pair programming and dedicated TDI2 champions
• Breaking Changes → Semantic versioning and deprecation periods
• Performance Issues → Comprehensive testing and rollback plans

Organizational Risks

• Team Resistance → Start with teams experiencing most pain
• Coordination Overhead → Clear ownership matrix and automated tracking

---

Success Metrics

Technical Success

• 90% reduction in components with 5+ props
• 50% reduction in test complexity
• 30% improvement in build performance
• Zero unplanned service interface breaking changes

Business Success

• 25% faster feature development
• 40% reduction in merge conflicts
• 60% faster new developer onboarding
• 50% reduction in state-related production bugs

---

Next Steps

Essential Reading

• Migration Strategy - Detailed migration planning
• Architectural Patterns - Controller vs Service distinction
• Service Patterns - Advanced service design

Examples

• Complete E-Commerce Implementation - Working enterprise example
• Team Onboarding Materials - Training resources
• Quality Gate Examples - Automated compliance

🎯 Key Takeaway

Start small with a pilot feature, prove value early, then systematically scale across teams. Clear service boundaries eliminate team conflicts and accelerate development.