ARCHITECTURE.md

AI Engine Architecture

Clean Architecture Implementation

This AI engine follows clean architecture principles with proper separation of concerns.

---

Module Structure

diagnosis/ai_engine/
├── detect_stuttering.py    # Main detector class (business logic)
├── model_loader.py         # Singleton pattern for model loading
└── features.py             # Feature extraction (ASR features)

---

Architecture Pattern

1. Model Loader (model_loader.py)

Responsibility: Singleton pattern for model instance management

• Ensures models are loaded only once
• Provides clean interface: get_stutter_detector()
• Handles initialization and error handling
• Used by API layer (app.py)

Usage:

from diagnosis.ai_engine.model_loader import get_stutter_detector

detector = get_stutter_detector()  # Singleton instance

---

2. Feature Extractor (features.py)

Responsibility: Feature extraction from audio using IndicWav2Vec Hindi

Class: ASRFeatureExtractor

Methods:

• extract_audio_features() - Raw audio feature extraction
• get_transcription_features() - Transcription with confidence scores
• get_word_level_features() - Word-level timestamps and confidence

Design Pattern:

• Takes pre-loaded model and processor as dependencies
• Single responsibility: feature extraction only
• Reusable across different use cases

Usage:

from .features import ASRFeatureExtractor

extractor = ASRFeatureExtractor(model, processor, device)
features = extractor.get_transcription_features(audio)

---

3. Detector (detect_stuttering.py)

Responsibility: High-level stutter detection orchestration

Class: AdvancedStutterDetector

Design:

• Uses feature extractor for transcription (composition)
• Orchestrates the analysis pipeline
• Returns structured results

Flow:

Audio Input
    ↓
Feature Extractor (ASR)
    ↓
Text Analysis
    ↓
Results

---

Benefits of This Architecture

✅ Separation of Concerns

• Model Loading: Isolated in model_loader.py
• Feature Extraction: Isolated in features.py
• Business Logic: In detect_stuttering.py

✅ Single Responsibility Principle

• Each module has one clear purpose
• Easy to test and maintain
• Easy to extend or replace components

✅ Dependency Injection

• Feature extractor receives model/processor as dependencies
• No tight coupling
• Easy to mock for testing

✅ Reusability

• Feature extractor can be used independently
• Model loader can be used by other modules
• Clean interfaces between layers

---

Data Flow

API Request (app.py)
    ↓
get_stutter_detector() [model_loader.py]
    ↓
AdvancedStutterDetector [detect_stuttering.py]
    ↓
ASRFeatureExtractor [features.py]
    ↓
IndicWav2Vec Hindi Model
    ↓
Results back through layers

---

Comparison with Django App

Before (Django App):

• Model loading logic in Django app
• Feature extraction in Django app
• Tight coupling between web app and ML logic

After (AI Engine Service):

• ✅ Model loading in AI engine service
• ✅ Feature extraction in AI engine service
• ✅ Django app only calls API (loose coupling)
• ✅ ML logic isolated in dedicated service

---

Extension Points

Adding New Features

1. Add method to ASRFeatureExtractor in features.py
2. Use in AdvancedStutterDetector via composition
3. No changes needed to model loader

Adding New Models

1. Update detect_stuttering.py to load new model
2. Create new feature extractor if needed
3. Model loader remains unchanged

Testing

• Mock ASRFeatureExtractor in tests
• Mock model loader for integration tests
• Each component can be tested independently

---

Key Principles Applied

1. Dependency Inversion: High-level modules don't depend on low-level modules
2. Open/Closed: Open for extension, closed for modification
3. Interface Segregation: Clean, focused interfaces
4. Don't Repeat Yourself (DRY): Feature extraction logic centralized
5. Single Source of Truth: Model instance managed by singleton

---

File Responsibilities

File	Responsibility	Depends On
model_loader.py	Singleton model management	detect_stuttering.py
features.py	Feature extraction	transformers, torch
detect_stuttering.py	Business logic orchestration	features.py, model_loader.py
app.py	API layer	model_loader.py

---

This architecture ensures the ML/AI logic stays in the AI engine service, not in the Django web application, following microservices best practices.