platform/docs/foundation_integration_guide.md

Foundation Integration Guide

Overview

This guide demonstrates how Level 0 and Level 1 packages work together to provide the foundation for the framework. It includes implementation priorities, integration patterns, and best practices.

Implementation Timeline

Phase 1: Core Foundation (Level 0)

Week 1: Contracts Package

Priority: Highest
Dependencies: None
Steps:
1. Define core interfaces
2. Create base exceptions
3. Add documentation
4. Write interface tests

Week 2: Support Package

Priority: Highest
Dependencies: Contracts
Steps:
1. Implement collections
2. Add string helpers
3. Create service provider base
4. Add utility functions

Weeks 3-4: Container Package

Priority: Highest
Dependencies: Contracts, Support
Steps:
1. Implement core container
2. Add contextual binding
3. Add method injection
4. Add tagged bindings
5. Implement caching

Week 5: Pipeline Package

Priority: High
Dependencies: Contracts, Support, Container
Steps:
1. Implement core pipeline
2. Add pipeline hub
3. Create middleware support
4. Add async handling

Phase 2: Infrastructure (Level 1)

Weeks 6-7: Events Package

Priority: High
Dependencies: All Level 0
Steps:
1. Implement event dispatcher
2. Add event discovery
3. Create subscriber support
4. Add queueing integration

Week 8: Config Package

Priority: High
Dependencies: All Level 0
Steps:
1. Implement config repository
2. Add environment loading
3. Create config caching
4. Add array casting

Weeks 9-10: FileSystem Package

Priority: High
Dependencies: All Level 0
Steps:
1. Implement filesystem manager
2. Create local driver
3. Add cloud drivers
4. Implement streaming

Integration Examples

1. Service Provider Integration

/// Example showing how packages integrate through service providers
void main() {
  var container = Container();
  
  // Register foundation services
  container.register(SupportServiceProvider());
  container.register(PipelineServiceProvider());
  container.register(EventServiceProvider());
  container.register(ConfigServiceProvider());
  container.register(FilesystemServiceProvider());
  
  // Boot application
  await container.bootProviders();
}

2. Event-Driven File Operations

/// Example showing Events and FileSystem integration
class FileUploadHandler {
  final EventDispatcherContract _events;
  final FilesystemContract _storage;
  
  Future<void> handleUpload(Upload upload) async {
    // Store file using FileSystem
    await _storage.put(
      'uploads/${upload.filename}',
      upload.contents,
      {'visibility': 'public'}
    );
    
    // Dispatch event using Events
    await _events.dispatch(FileUploaded(
      filename: upload.filename,
      size: upload.size,
      url: await _storage.url('uploads/${upload.filename}')
    ));
  }
}

3. Configuration-Based Pipeline

/// Example showing Config and Pipeline integration
class RequestHandler {
  final ConfigContract _config;
  final Pipeline<Request> _pipeline;
  
  Future<Response> handle(Request request) async {
    // Get middleware from config
    var middleware = _config.get<List>('http.middleware', [])
      .map((m) => container.make<Middleware>(m))
      .toList();
    
    // Process request through pipeline
    return _pipeline
      .through(middleware)
      .send(request)
      .then((request) => processRequest(request));
  }
}

Common Integration Patterns

1. Service Provider Pattern

abstract class ServiceProvider {
  void register() {
    container.singleton<Service>((c) => 
      ServiceImpl(
        c.make<EventDispatcherContract>(),
        c.make<ConfigContract>(),
        c.make<FilesystemContract>()
      )
    );
  }
}

2. Event-Driven Pattern

class EventDrivenService {
  final EventDispatcherContract events;
  
  void initialize() {
    events.listen<ConfigurationChanged>(_handleConfigChange);
    events.listen<StorageEvent>(_handleStorageEvent);
  }
}

3. Pipeline Pattern

class ServicePipeline {
  final Pipeline<Request> pipeline;
  
  ServicePipeline(this.pipeline) {
    pipeline.through([
      ConfigMiddleware(container.make<ConfigContract>()),
      EventMiddleware(container.make<EventDispatcherContract>()),
      StorageMiddleware(container.make<FilesystemContract>())
    ]);
  }
}

Testing Strategy

1. Unit Tests

void main() {
  group('Package Tests', () {
    test('core functionality', () {
      // Test core features
    });
    
    test('integration points', () {
      // Test integration with other packages
    });
  });
}

2. Integration Tests

void main() {
  group('Integration Tests', () {
    late Container container;
    
    setUp(() {
      container = Container();
      container.register(SupportServiceProvider());
      container.register(EventServiceProvider());
    });
    
    test('should handle file upload with events', () async {
      var handler = container.make<FileUploadHandler>();
      var events = container.make<EventDispatcherContract>();
      
      var received = <FileUploaded>[];
      events.listen<FileUploaded>((event) {
        received.add(event);
      });
      
      await handler.handleUpload(testUpload);
      expect(received, hasLength(1));
    });
  });
}

Quality Checklist

1. Code Quality

• Follows style guide
• Uses static analysis
• Has documentation
• Has tests
• Handles errors

2. Package Quality

• Has README
• Has examples
• Has changelog
• Has license
• Has CI/CD

3. Integration Quality

• Works with container
• Supports events
• Uses configuration
• Has providers

Best Practices

1. Use Service Providers

// Register dependencies in providers
class ServiceProvider {
  void register() {
    // Register all required services
  }
}

2. Event-Driven Communication

// Use events for cross-package communication
class Service {
  final EventDispatcherContract _events;
  
  Future<void> doSomething() async {
    await _events.dispatch(SomethingHappened());
  }
}

3. Configuration-Based Setup

// Use configuration for service setup
class Service {
  void initialize(ConfigContract config) {
    if (config.get('service.enabled')) {
      // Initialize service
    }
  }
}

Next Steps

1. Follow implementation timeline
2. Review package dependencies
3. Implement integration tests
4. Document common patterns
5. Create example applications

Would you like me to:

1. Start implementing a specific package?
2. Create detailed integration tests?
3. Build example applications?