Clean Architecture Refactoring: Fix Layer Boundaries & Modularization

[buddhasaikia]

Problem Statement

ThreadSimulator has good Clean Architecture foundation (70% aligned) but violates key principles:

• UI layer imports data layer directly (MockDataSource in HomeScreenRoute.kt)
• ViewModel bypasses domain layer (accesses repository directly for initial data)
• Business logic in ViewModel (channel management, throttle selection should be in domain)
• Tight coupling to infrastructure (ViewModel manages 6+ dependencies)
• Monolithic structure (no feature modules for independent build/test)

Solution: Two-Phase Refactoring

Phase 1: Fix Layer Boundaries (Critical/High)

• Create GetCompanyListUseCase
• Create StreamCoordinationService (Domain)
• Extract channel management from ViewModel
• Refactor HomeViewModel dependencies (6+ → 3-4)
• Remove MockDataSource import from UI layer
• Verify InitCompanyListUseCase exists
• Update ViewModel to use only use cases
• Run tests and verify no regressions

Goal: Enforce UI-Domain-Data dependency rules. Outcome: 85-90% alignment.

Phase 2: Modularization (Medium Priority)

• Create :core:common module
• Create :core:model module
• Create :core:di module
• Create :feature:stockData module
• Update app module build.gradle
• Update imports across codebase
• Verify modular build and tests

Goal: Enable independent feature modules. Outcome: 95%+ alignment.

Validation Checklist

After Phase 1:

• No imports of com.bs.threadsimulator.data.* in UI layer
• ViewModel imports only from domain layer
• ViewModel constructor has 3-4 dependencies max
• All tests pass: ./gradlew test
• App builds: ./gradlew assembleDebug

After Phase 2:

• Each module builds independently
• No circular dependencies
• Full app build succeeds: ./gradlew build

Effort

• Phase 1: 3-5 hours
• Phase 2: 4-6 hours

Backward Compatible: No breaking changes, public APIs unchanged.

See full plan in session workspace: plan.md

[buddhasaikia]

Phase 1 Subtasks: Fix Layer Boundaries

1. Create GetCompanyListUseCase

Depends on: None

Create domain/usecase/GetCompanyListUseCase.kt that wraps repository.getCompanyList().

• Provides single domain-facing entry point for company list fetching
• Allows ViewModel to depend on domain-only (no data layer imports)
• Impact: Removes direct repository access from ViewModel

2. Create StreamCoordinationService (Domain)

Depends on: None

Create domain/service/StreamCoordinationService.kt to handle:

• Channel creation and management
• Job lifecycle tracking
• Queue depth calculation
• Throttle strategy selection
• Expose Flow-based API for ViewModel to consume
• Impact: Infrastructure/channel logic moved from ViewModel to domain

3. Extract Channel Management Logic from ViewModel

Depends on: Subtask 2

Move from HomeViewModel:

• _activeJobs list management
• Channel creation logic
• Queue depth calculation (lines 118-132)
• Throttle strategy selection logic
• Export as: startStreamCollection(useCase: UseCase): Flow<Company>
• Impact: ViewModel becomes simpler, orchestration centralized

4. Refactor HomeViewModel Dependencies

Depends on: Subtasks 1, 3

Reduce constructor from 6+ to 3-4 injections:

• Remove: StockRepository, ThreadMonitor, ChannelConfig, direct AppDispatchers
• Keep: GetCompanyListUseCase, StreamCoordinationService, 3x Fetch*UseCase
• Pass AppDispatchers through StreamCoordinationService
• Impact: Clean dependency boundaries, ViewModel respects Clean Architecture

5. Remove MockDataSource from HomeScreenRoute.kt

Depends on: Subtask 4

• Remove line 41: import com.bs.threadsimulator.data.MockDataSource
• This violates UI-data layer boundary
• All init logic should flow through ViewModel/use cases
• Impact: No UI-data imports, enforced boundary

6. Verify InitCompanyListUseCase Exists

Depends on: None

Ensure domain/usecase/InitCompanyListUseCase.kt exists and properly:

• Calls repository.initCompanyList()
• Handles initialization concerns
• Can be tested independently
• Impact: Single path for init logic

7. Update ViewModel to Use Only Use Cases

Depends on: Subtasks 4, 1, 6

Refactor HomeViewModel:

• Replace stockRepository.getCompanyList() with getCompanyListUseCase
• Update all direct repository calls (lines 82, 199, 216)
• Ensure init uses InitCompanyListUseCase
• All data access flows through use cases
• Impact: ViewModel no longer directly accesses data layer

8. Run Tests & Verify No Regressions

Depends on: Subtask 7

• Run ./gradlew test (unit tests)
• Run ./gradlew connectedAndroidTest (instrumented tests)
• Verify ./gradlew assembleDebug succeeds
• Confirm HomeScreen renders with same behavior
• Check no new import errors
• Impact: Phase 1 complete and validated

[buddhasaikia]

Phase 2 Subtasks: Modularization (Conditional - Start After Phase 1)

M1. Create :core:common Module

Depends on: Phase 1 complete

Create new Gradle module with:

• Extract common/ThreadMonitor.kt
• Extract common/AppDispatchers.kt
• Extract common/ChannelConfig.kt
• Extract utilities and helpers
• Create build.gradle.kts for independent build
• Impact: Common utilities as independent library

M2. Create :core:model Module

Depends on: Phase 1 complete

Create new Gradle module with:

• Extract model/Resource.kt
• Extract domain models: CompanyData.kt, Stock.kt, etc.
• Extract all mappers (DataToDomainMapper.kt, DomainToUIMapper.kt, etc.)
• Extract UI models: Company.kt, StateError.kt, etc.
• Create build.gradle.kts
• Impact: Shared models used by all feature modules

M3. Create :core:di Module

Depends on: M1, M2

Create new Gradle module with:

• Move di/AppModule.kt
• Move di/RepositoryModule.kt
• Create entry points for features to inject dependencies
• Configure Hilt module structure
• Impact: Centralized DI configuration, reusable across features

M4. Create :feature:stockData Module

Depends on: M1, M2, M3

Create new Gradle module with:

• Migrate data/ directory
• Migrate domain/usecase/ directory
• Migrate domain/service/ directory
• Migrate ui/screens/ (exclude MainActivity)
• Create feature-level DI if needed
• Create build.gradle.kts with dependencies on core modules
• Impact: Feature module encapsulates stock data functionality

M5. Update app Module build.gradle

Depends on: M1, M2, M3, M4

Configure app module to:

• Remove data/, domain/, and ui/screens/ packages
• Add dependencies:
  • implementation project(':core:common')
  • implementation project(':core:model')
  • implementation project(':core:di')
  • implementation project(':feature:stockData')
• Keep only: MainActivity, App.kt, entry points
• Update AndroidManifest.xml if needed
• Impact: app module becomes lightweight entry point

M6. Update Imports Across Codebase

Depends on: M1, M2, M3, M4, M5

• Fix imports in :feature:stockData to reference :core:* modules
• Fix imports in app/ to reference :feature:*
• Update Composable/ViewModel imports for new package structure
• Resolve any unresolved symbol errors
• Update AndroidManifest references
• Impact: Code compiles with new module structure

M7. Verify Modular Build & Tests

Depends on: M1, M2, M3, M4, M5, M6

• Build :core:common independently: ./gradlew :core:common:build
• Build :core:model independently: ./gradlew :core:model:build
• Build :core:di independently: ./gradlew :core:di:build
• Build :feature:stockData independently: ./gradlew :feature:stockData:build
• Run all tests: ./gradlew build
• Verify no circular dependencies: ./gradlew :app:dependencies
• Confirm app runs end-to-end
• Impact: Phase 2 complete, modular architecture validated

---

Final Validation

After both phases, the codebase should achieve:

• ✅ 95%+ Clean Architecture alignment
• ✅ No layer boundary violations
• ✅ Independent feature modules
• ✅ Modular build/test cycles
• ✅ Reduced app module coupling
• ✅ Foundation for multi-screen growth

[buddhasaikia]

Additional Resources

Detailed Validation Checklist

After Phase 1 - Layer Boundaries Fixed:

• No imports of com.bs.threadsimulator.data.* found in ui/ package
• ViewModel imports only from domain/ layer (use cases/services)
• HomeViewModel constructor reduced to ≤4 dependencies
• All unit tests pass: ./gradlew test
• All instrumented tests pass: ./gradlew connectedAndroidTest
• App builds successfully: ./gradlew assembleDebug
• HomeScreen renders with identical behavior
• No new lint warnings introduced

After Phase 2 - Modularization Complete:

• :core:common builds independently without app module
• :core:model builds independently without app module
• :core:di builds independently without app module
• :feature:stockData builds independently without app module
• app module only imports from feature/core modules (no data/domain/ui)
• No circular dependencies detected
• All module tests pass: ./gradlew :core:common:test, etc.
• Full app build succeeds: ./gradlew build
• No import errors or unresolved symbols
• App runs end-to-end with same functionality

Effort Breakdown

Phase	Task	Effort
Phase 1	Create use cases (2)	1 hr
	Create domain service	1.5 hrs
	Refactor ViewModel	1 hr
	Remove UI-data imports	0.5 hr
	Test & verify	1 hr
Phase 1 Total		5 hrs
Phase 2	Create core modules (3)	2 hrs
	Create feature module	2 hrs
	Update imports & build files	1.5 hrs
	Verify modular build	0.5 hr
Phase 2 Total		6 hrs
Combined	Full refactoring	11 hrs

Estimates assume one developer with Android/Kotlin experience. Can be optimized with parallel work.

Risk Mitigation Strategy

✅ No Breaking Changes: Public APIs (ViewModel methods, Composables) unchanged
✅ Backward Compatibility: UI behavior identical throughout refactoring
✅ Test Coverage: Existing tests ensure regressions caught immediately
✅ Incremental: Each subtask can be reviewed and merged independently
✅ Rollback Plan: If issues arise, revert last commit (single atomic change per subtask)

Success Metrics

After completion, ThreadSimulator will demonstrate:

• ✅ Clean Architecture alignment from 70% → 95%+
• ✅ Layer boundaries enforced (no illegal imports)
• ✅ ViewModel testability improved (fewer dependencies)
• ✅ Foundation for multi-screen architecture ready
• ✅ Reduced future maintenance burden
• ✅ Patterns documented for future features

---

To Start Phase 1: Assign to yourself and begin with Subtask 1.
To Start Phase 2: Wait for Phase 1 completion notification.
Questions?: Comment on this issue with questions about any subtask.