MODULAR_ARCHITECTURE.md

🏗️ Modüler Mimari ve Bağımlılık İzolasyonu

🎯 MODÜLER TASARIM FELSEFESİ

Temel İlkeler:

1. 🔒 STRICT SEPARATION - Her modül kendi sorumluluğunda
2. 🛡️ FAIL-SAFE DESIGN - Bir modül çökerse diğerleri çalışmaya devam etsin
3. 🔧 LOOSE COUPLING - Modüller arası minimum bağımlılık
4. 📦 HIGH COHESION - Modül içi güçlü bağlılık
5. 🔄 SINGLE RESPONSIBILITY - Her modül tek görev

📁 KATMAN BAZLI MODÜLER YAPISI

1. PRESENTATION LAYER (Frontend Modules)

frontend/
├── modules/
│   ├── authentication/          # 🔐 Kimlik doğrulama modülü
│   │   ├── components/
│   │   │   ├── LoginForm/
│   │   │   │   ├── LoginForm.tsx
│   │   │   │   ├── LoginForm.module.css    # ⚡ SADECE LoginForm için CSS
│   │   │   │   ├── LoginForm.test.tsx
│   │   │   │   └── index.ts
│   │   │   ├── RegisterForm/
│   │   │   │   ├── RegisterForm.tsx
│   │   │   │   ├── RegisterForm.module.css  # ⚡ Izole CSS
│   │   │   │   ├── RegisterForm.test.tsx
│   │   │   │   └── index.ts
│   │   │   └── PasswordReset/
│   │   ├── hooks/
│   │   │   ├── useAuth.ts
│   │   │   ├── useLogin.ts
│   │   │   └── useRegister.ts
│   │   ├── services/
│   │   │   ├── authAPI.ts              # ⚡ Sadece auth API calls
│   │   │   └── tokenService.ts
│   │   ├── types/
│   │   │   └── auth.types.ts
│   │   ├── store/
│   │   │   └── authStore.ts            # ⚡ Izole state management
│   │   └── index.ts                    # ⚡ Module public interface
│   │
│   ├── data-manipulation/          # 📊 Veri işleme modülü
│   │   ├── components/
│   │   │   ├── FileUpload/
│   │   │   │   ├── FileUpload.tsx
│   │   │   │   ├── FileUpload.module.css    # ⚡ Izole stil
│   │   │   │   ├── FileUpload.test.tsx
│   │   │   │   └── index.ts
│   │   │   ├── DataViewer/
│   │   │   │   ├── DataViewer.tsx
│   │   │   │   ├── DataViewer.module.css
│   │   │   │   └── index.ts
│   │   │   ├── ProcessingQueue/
│   │   │   └── ResultsDisplay/
│   │   ├── hooks/
│   │   │   ├── useFileUpload.ts
│   │   │   ├── useDataProcessing.ts
│   │   │   └── useResults.ts
│   │   ├── services/
│   │   │   ├── fileAPI.ts
│   │   │   ├── processingAPI.ts
│   │   │   └── downloadAPI.ts
│   │   ├── utils/
│   │   │   ├── fileValidation.ts
│   │   │   ├── dataTransformation.ts
│   │   │   └── formatters.ts
│   │   ├── types/
│   │   │   └── dataManipulation.types.ts
│   │   ├── store/
│   │   │   └── dataStore.ts
│   │   └── index.ts
│   │
│   ├── ai-music-detector/          # 🎵 AI müzik detektörü modülü
│   │   ├── components/
│   │   │   ├── AudioUpload/
│   │   │   │   ├── AudioUpload.tsx
│   │   │   │   ├── AudioUpload.module.css   # ⚡ Audio-specific styles
│   │   │   │   └── index.ts
│   │   │   ├── Waveform/
│   │   │   │   ├── Waveform.tsx
│   │   │   │   ├── Waveform.module.css
│   │   │   │   └── waveform.worker.ts       # ⚡ Web Worker izolasyonu
│   │   │   ├── DetectionResults/
│   │   │   └── AnalysisChart/
│   │   ├── hooks/
│   │   │   ├── useAudioProcessing.ts
│   │   │   ├── useAIDetection.ts
│   │   │   └── useWaveform.ts
│   │   ├── services/
│   │   │   ├── audioAPI.ts
│   │   │   ├── aiModelService.ts           # ⚡ AI model izolasyonu
│   │   │   └── analysisAPI.ts
│   │   ├── models/                         # ⚡ AI modelleri izole
│   │   │   ├── musicDetector.ts
│   │   │   ├── featureExtractor.ts
│   │   │   └── modelLoader.ts
│   │   ├── utils/
│   │   │   ├── audioProcessing.ts
│   │   │   ├── featureExtraction.ts
│   │   │   └── visualization.ts
│   │   ├── types/
│   │   │   └── aiDetection.types.ts
│   │   ├── store/
│   │   │   └── aiStore.ts
│   │   └── index.ts
│   │
│   └── shared/                     # 🔄 Paylaşılan modüller
│       ├── components/
│       │   ├── Layout/
│       │   │   ├── Header/
│       │   │   │   ├── Header.tsx
│       │   │   │   ├── Header.module.css   # ⚡ Header-only styles
│       │   │   │   └── index.ts
│       │   │   ├── Footer/
│       │   │   │   ├── Footer.tsx
│       │   │   │   ├── Footer.module.css   # ⚡ Footer-only styles
│       │   │   │   └── index.ts
│       │   │   └── Sidebar/
│       │   ├── UI/
│       │   │   ├── Button/
│       │   │   │   ├── Button.tsx
│       │   │   │   ├── Button.module.css   # ⚡ Button variants
│       │   │   │   ├── Button.test.tsx
│       │   │   │   └── index.ts
│       │   │   ├── Modal/
│       │   │   ├── Toast/
│       │   │   └── LoadingSpinner/
│       │   └── Forms/
│       ├── hooks/
│       │   ├── useLocalStorage.ts
│       │   ├── useDebounce.ts
│       │   └── useApi.ts
│       ├── utils/
│       │   ├── constants.ts
│       │   ├── formatters.ts
│       │   └── validators.ts
│       ├── services/
│       │   ├── httpClient.ts               # ⚡ HTTP client izolasyonu
│       │   └── errorHandler.ts
│       └── types/
│           └── common.types.ts

2. BUSINESS LOGIC LAYER (Backend Modules — FastAPI on HuggingFace Spaces)

hf-crowncode-backend/
├── modules/
│   ├── auth/                       # 🔐 Kimlik doğrulama API modülü
│   │   ├── routers/
│   │   │   └── auth_router.py             # ⚡ Sadece auth endpoints
│   │   ├── services/
│   │   │   ├── auth_service.py
│   │   │   ├── token_service.py
│   │   │   └── password_service.py
│   │   ├── models/
│   │   │   ├── user.py                     # ⚡ User model izole
│   │   │   └── session.py
│   │   ├── dependencies/
│   │   │   ├── auth_deps.py
│   │   │   └── rate_limit.py
│   │   ├── schemas/
│   │   │   └── auth_schemas.py             # ⚡ Pydantic schemas
│   │   └── __init__.py
│   │
│   ├── data-processing/            # 📊 Veri işleme API modülü
│   │   ├── routers/
│   │   │   ├── upload_router.py
│   │   │   ├── processing_router.py
│   │   │   └── download_router.py
│   │   ├── services/
│   │   │   ├── file_processing_service.py  # ⚡ File ops izole
│   │   │   ├── data_transform_service.py
│   │   │   └── queue_service.py
│   │   ├── processors/                     # ⚡ İşleme algoritmları izole
│   │   │   ├── csv_processor.py
│   │   │   ├── json_processor.py
│   │   │   ├── excel_processor.py
│   │   │   └── data_multiplier.py
│   │   ├── models/
│   │   │   ├── data_upload.py
│   │   │   ├── processing_job.py
│   │   │   └── processed_file.py
│   │   ├── dependencies/
│   │   │   ├── file_upload_deps.py
│   │   │   └── processing_deps.py
│   │   ├── schemas/
│   │   │   └── data_schemas.py
│   │   └── __init__.py
│   │
│   ├── ai-detection/               # 🎵 AI müzik detektörü API modülü
│   │   ├── routers/
│   │   │   ├── audio_upload_router.py
│   │   │   ├── detection_router.py
│   │   │   └── analysis_router.py
│   │   ├── services/
│   │   │   ├── audio_processing_service.py # ⚡ Audio ops izole
│   │   │   ├── ai_model_service.py
│   │   │   └── feature_extraction_service.py
│   │   ├── models/
│   │   │   ├── audio_analysis.py
│   │   │   ├── detection_result.py
│   │   │   └── audio_file.py
│   │   ├── ai_engine/                      # ⚡ AI engine tamamen izole
│   │   │   ├── model_loader.py
│   │   │   ├── feature_extractor.py
│   │   │   ├── predictor.py
│   │   │   └── model_trainer.py
│   │   ├── dependencies/
│   │   │   ├── audio_upload_deps.py
│   │   │   └── audio_validation_deps.py
│   │   ├── schemas/
│   │   │   └── ai_detection_schemas.py
│   │   └── __init__.py
│   │
│   ├── automation/                 # 🤖 Otomasyon modülü
│   │   ├── services/
│   │   │   ├── data_collection_service.py  # ⚡ Dataset toplama izole
│   │   │   ├── model_training_service.py
│   │   │   └── deployment_service.py
│   │   ├── schedulers/
│   │   │   ├── daily_scheduler.py
│   │   │   └── weekly_scheduler.py
│   │   ├── collectors/                     # ⚡ Data collectors izole
│   │   │   ├── ai_music_collector.py
│   │   │   ├── human_music_collector.py
│   │   │   └── quality_controller.py
│   │   ├── models/
│   │   │   └── automation_job.py
│   │   ├── schemas/
│   │   │   └── automation_schemas.py
│   │   └── __init__.py
│   │
│   └── shared/                     # 🔄 Paylaşılan backend modüller
│       ├── database/
│       │   ├── connection.py               # ⚡ DB connection izole
│       │   ├── migrations/
│       │   └── seeds/
│       ├── dependencies/
│       │   ├── error_handler.py
│       │   ├── logger.py
│       │   └── cors_config.py
│       ├── services/
│       │   ├── storage_service.py          # ⚡ File storage izole
│       │   ├── email_service.py
│       │   └── notification_service.py
│       ├── utils/
│       │   ├── logger.py
│       │   ├── encryption.py
│       │   └── validators.py
│       └── schemas/
│           └── common_schemas.py

3. DATA LAYER (Database Modules)

database/
├── modules/
│   ├── user-management/            # 👤 Kullanıcı veri modülü
│   │   ├── schemas/
│   │   │   ├── users.sql
│   │   │   └── sessions.sql
│   │   ├── migrations/
│   │   │   ├── 001_create_users.sql
│   │   │   └── 002_create_sessions.sql
│   │   ├── seeds/
│   │   │   └── default_users.sql
│   │   └── indexes/
│   │       └── user_indexes.sql
│   │
│   ├── data-processing/            # 📊 Veri işleme DB modülü
│   │   ├── schemas/
│   │   │   ├── data_uploads.sql
│   │   │   ├── processing_jobs.sql
│   │   │   └── processed_files.sql
│   │   ├── migrations/
│   │   └── indexes/
│   │
│   ├── ai-detection/               # 🎵 AI detektörü DB modülü
│   │   ├── schemas/
│   │   │   ├── audio_analyses.sql
│   │   │   ├── detection_results.sql
│   │   │   └── model_versions.sql
│   │   ├── migrations/
│   │   └── indexes/
│   │
│   └── automation/                 # 🤖 Otomasyon DB modülü
│       ├── schemas/
│       │   ├── automation_jobs.sql
│       │   └── dataset_metadata.sql
│       ├── migrations/
│       └── indexes/

🛡️ FAIL-SAFE DESIGN PATTERNS

1. Circuit Breaker Pattern

// shared/services/circuitBreaker.ts
export class CircuitBreaker {
  private failureCount = 0
  private lastFailTime = 0
  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED'

  constructor(
    private readonly threshold = 5,
    private readonly timeout = 60000
  ) {}

  async execute<T>(operation: () => Promise<T>): Promise<T> {
    if (this.state === 'OPEN') {
      if (Date.now() - this.lastFailTime > this.timeout) {
        this.state = 'HALF_OPEN'
      } else {
        throw new Error('Circuit breaker is OPEN')
      }
    }

    try {
      const result = await operation()
      this.onSuccess()
      return result
    } catch (error) {
      this.onFailure()
      throw error
    }
  }

  private onSuccess() {
    this.failureCount = 0
    this.state = 'CLOSED'
  }

  private onFailure() {
    this.failureCount++
    this.lastFailTime = Date.now()

    if (this.failureCount >= this.threshold) {
      this.state = 'OPEN'
    }
  }
}

// Her modül kendi circuit breaker'ını kullanır
export const authCircuitBreaker = new CircuitBreaker(3, 30000)
export const aiModelCircuitBreaker = new CircuitBreaker(5, 60000)
export const dataProcessingCircuitBreaker = new CircuitBreaker(10, 120000)

2. Module Health Monitoring

// shared/services/healthMonitor.ts
interface ModuleHealth {
  name: string
  status: 'healthy' | 'degraded' | 'unhealthy'
  lastCheck: Date
  dependencies: string[]
  metrics: {
    responseTime: number
    errorRate: number
    throughput: number
  }
}

export class ModuleHealthMonitor {
  private healthStatus = new Map<string, ModuleHealth>()

  async checkModuleHealth(moduleName: string): Promise<ModuleHealth> {
    const startTime = Date.now()

    try {
      // Module-specific health check
      await this.performHealthCheck(moduleName)

      const responseTime = Date.now() - startTime
      const health: ModuleHealth = {
        name: moduleName,
        status: responseTime < 1000 ? 'healthy' : 'degraded',
        lastCheck: new Date(),
        dependencies: this.getModuleDependencies(moduleName),
        metrics: {
          responseTime,
          errorRate: this.calculateErrorRate(moduleName),
          throughput: this.calculateThroughput(moduleName)
        }
      }

      this.healthStatus.set(moduleName, health)
      return health
    } catch (error) {
      const health: ModuleHealth = {
        name: moduleName,
        status: 'unhealthy',
        lastCheck: new Date(),
        dependencies: [],
        metrics: {
          responseTime: Date.now() - startTime,
          errorRate: 1,
          throughput: 0
        }
      }

      this.healthStatus.set(moduleName, health)
      return health
    }
  }

  // Eğer bir modül unhealthy ise, bağımlı modüller graceful degradation yapar
  async checkDependencies(moduleName: string): Promise<boolean> {
    const module = this.healthStatus.get(moduleName)
    if (!module) return false

    for (const dependency of module.dependencies) {
      const depHealth = await this.checkModuleHealth(dependency)
      if (depHealth.status === 'unhealthy') {
        // Dependency unhealthy - implement fallback
        await this.enableFallbackMode(moduleName, dependency)
        return false
      }
    }

    return true
  }
}

3. Module Interface Contracts

// Her modül strict interface contract'ı implement eder
// modules/auth/index.ts
export interface AuthModuleInterface {
  // Public API - diğer modüller sadece bunları kullanabilir
  login(credentials: LoginCredentials): Promise<AuthResult>
  logout(token: string): Promise<void>
  validateToken(token: string): Promise<boolean>
  refreshToken(refreshToken: string): Promise<AuthResult>

  // Health check
  healthCheck(): Promise<ModuleHealth>

  // Graceful shutdown
  shutdown(): Promise<void>
}

export class AuthModule implements AuthModuleInterface {
  private circuitBreaker = authCircuitBreaker
  private healthMonitor = new ModuleHealthMonitor()

  async login(credentials: LoginCredentials): Promise<AuthResult> {
    return this.circuitBreaker.execute(async () => {
      // Login implementation
      return await this.authService.authenticate(credentials)
    })
  }

  async healthCheck(): Promise<ModuleHealth> {
    return this.healthMonitor.checkModuleHealth('auth')
  }

  async shutdown(): Promise<void> {
    // Graceful shutdown - finish pending operations
    await this.authService.finishPendingOperations()
    await this.database.closeConnections()
  }
}

// Diğer modüller sadece interface üzerinden erişir
// modules/data-processing/services/dataService.ts
import { AuthModuleInterface } from '../auth'

export class DataProcessingService {
  constructor(
    private authModule: AuthModuleInterface  // Interface dependency
  ) {}

  async processFile(file: File, userToken: string): Promise<ProcessingResult> {
    // Auth modülünün sağlığını kontrol et
    const authHealth = await this.authModule.healthCheck()

    if (authHealth.status === 'unhealthy') {
      // Fallback: process without user context
      return this.processAnonymously(file)
    }

    // Normal flow
    const isValid = await this.authModule.validateToken(userToken)
    if (!isValid) {
      throw new UnauthorizedError()
    }

    return this.processWithUserContext(file, userToken)
  }
}

🔧 MODULE DEPENDENCY INJECTION

Dependency Container

// shared/container/diContainer.ts
export class DIContainer {
  private services = new Map<string, any>()
  private factories = new Map<string, () => any>()

  // Singleton registration
  registerSingleton<T>(name: string, factory: () => T): void {
    this.factories.set(name, factory)
  }

  // Get service with lazy loading
  get<T>(name: string): T {
    if (!this.services.has(name)) {
      const factory = this.factories.get(name)
      if (!factory) {
        throw new Error(`Service ${name} not registered`)
      }
      this.services.set(name, factory())
    }
    return this.services.get(name)
  }

  // Clear service (for testing)
  clear(name: string): void {
    this.services.delete(name)
  }
}

// Module registration
// app.ts
const container = new DIContainer()

// Auth module
container.registerSingleton('authModule', () => new AuthModule())

// Data processing module (depends on auth)
container.registerSingleton('dataModule', () =>
  new DataProcessingModule(container.get('authModule'))
)

// AI detection module (depends on auth and data)
container.registerSingleton('aiModule', () =>
  new AIDetectionModule(
    container.get('authModule'),
    container.get('dataModule')
  )
)

Bu modüler yapı ile:

• ✅ Bir modül çökerse diğerleri etkilenmez
• ✅ Her modül kendi CSS'ine sahip
• ✅ Strict interface contracts
• ✅ Circuit breaker protection
• ✅ Health monitoring
• ✅ Graceful degradation
• ✅ Easy testing and mocking
• ✅ Independent deployment possible