# App Architecture

> **Note**: This document is automatically generated by AI and updated on a weekly basis to ensure it stays in sync with the codebase. You can view the GitHub Actions workflow [here](../.github/workflows/sync_docs.yaml) and [trigger it manually](../.github/workflows/sync_docs.yaml) if needed.

---

## Libraries, Frameworks and Design Patterns

### Dependency Injection

- Hilt for DI throughout the app
- Module-level component providers
- Scoped dependencies management

### State Management

- MVI architecture pattern
- Kotlin Flow for reactive streams
- StateFlow for UI state
- SharedFlow for events

### Threading Model

- Coroutines for async operations
- CoroutineScope management
- Dispatchers usage patterns
- Background work handling

### Data Flow

```
UI Layer (Compose) → ViewModel → Repository → [Network/Database]
     ↑                   ↑          ↓              ↓
     └───────────── StateFlow ←─────┴──────────────┘
```

### Security Implementation

- Certificate pinning for network requests
- Encrypted preferences for sensitive data
- Token management for authentication
- ProGuard/R8 configuration

### Testing Strategy

- Unit tests: JUnit, Mockk
- UI tests: Compose testing
- Integration tests: Hilt testing
- Automated testing setup

### Performance Considerations

- Lazy loading patterns
- Memory management
- Background task optimization
- Image loading optimization

## Modularization

```
app/
 ├── common-ui/
 ├── common-data/
 │    ├── common-networking/
 │    └── common-db/
 ├── common-res/
 ├── common-core-utils/
 ├── common-media/
 ├── common-analytics/
 ├── common-gating/
 └── common-i18n/
```

Each module maintains its own dependency scope and exposes only necessary public APIs through interfaces.

## Core Architecture Components

### Application Layer (`app/`)

#### Key Classes

- [`SunoApp`](app/src/main/java/com/suno/android/app/SunoApp.kt): Application class
    - Initializes core services (Analytics, Push Notifications, Media, etc.)
    - Configures CameraX
    - Sets up dependency injection

- [`MainActivity`](app/src/main/java/com/suno/android/MainActivity.kt): Single-activity architecture
    - Handles deep linking and push notifications via [`MainActivityVM`](app/src/main/java/com/suno/android/MainActivityVM.kt)
    - Manages app lifecycle
    - Entry point for Compose navigation

- [`PlaybackMediaLibraryService`](app/src/main/java/com/suno/android/media/PlaybackMediaLibraryService.kt): Media3-based service
    - Handles background audio playback
    - Manages media session and notifications
    - Syncs playback state with UI

#### Core Features Implementation

- **Deep Linking**: Implemented via [`DeferredDeepLinkManager`](app/src/main/java/com/suno/android/deeplink/DeferredDeepLinkManager.kt)
    - Supports both https and custom scheme (suno://) links
    - Handles OAuth redirects and content sharing

- **Push Notifications**: Dual provider system
    - Firebase Cloud Messaging for delivery via [`FirebaseMessagingService`](app/src/main/java/com/suno/android/notifications/FirebaseMessagingService.kt)
    - Braze for rich content and analytics
    - Custom notification channels for different content types

### Data Layer

#### Common Data (`common-data/`)

Core data management module implementing repository pattern.

**Resposibilities:**

- Repository implementations
- Data models and mappers
- Business logic implementations
- State management using Kotlin Flow

**Key Classes:**

- Data repositories (e.g., [`UserRepository`](common-data/src/main/java/com/suno/android/common_data/user/UserRepository.kt), [`MediaRepository`](common-data/src/main/java/com/suno/android/common_data/media/MediaRepository.kt))
- Domain models and mappers in [`models`](common-data/src/main/java/com/suno/android/common_data/models/)
- Use cases for business logic in [`usecases`](common-data/src/main/java/com/suno/android/common_data/usecases/)
- State holders for UI data

#### Common DB (`common-db/`)

Local persistence layer using Room.

**Resposibilities:**

- Database schema and migrations
- DAOs (Data Access Objects)
- Entity definitions
- Type converters

**Key Classes:**

- [`SunoAppDatabase`](common-db/src/main/java/com/suno/android/common_db/database/SunoAppDatabase.kt): Room database configuration
- Entity classes in [`entities`](common-db/src/main/java/com/suno/android/common_db/entities/)
- DAO interfaces in [`dao`](common-db/src/main/java/com/suno/android/common_db/dao/)
- Migration helpers in [`migrations`](common-db/src/main/java/com/suno/android/common_db/migrations/)

#### Common Networking (`common-networking/`)

Network layer using Retrofit and OkHttp.

**Resposibilities:**

- API client configuration
- Network interceptors
- Response handling
- Error mapping

**Key Classes:**

- API service interfaces in [`remote`](common-networking/src/main/java/com/suno/android/common_networking/remote/)
- Network models in [`entities`](common-networking/src/main/java/com/suno/android/common_networking/remote/entities/)
- Custom interceptors in [`interceptors`](common-networking/src/main/java/com/suno/android/common_networking/interceptors/)
- Error handlers in [`errors`](common-networking/src/main/java/com/suno/android/common_networking/errors/)

### Media Layer (`common-media/`)

**Resposibilities:**

- Media playback engine using Media3
- Metadata management
- Audio session handling
- Background playback support

**Key Classes:**

- [`MediaManager`](app/src/main/java/com/suno/android/media/MediaManager.kt): Core playback orchestrator
- [`MediaMetadataManager`](app/src/main/java/com/suno/android/media/MediaMetadataManager.kt): Handles media metadata
- [`PlaybackMediaLibraryService`](app/src/main/java/com/suno/android/media/PlaybackMediaLibraryService.kt): Background service
- Media state managers like [`MediaAnalyticsManager`](app/src/main/java/com/suno/android/media/MediaAnalyticsManager.kt)

### UI Layer

#### Common UI (`common-ui/`)

Shared UI components and theming.

**Resposibilities:**

- Reusable Compose components
- Theme definitions
- UI utilities
- Common layouts and animations

**Key Classes:**

- Theme components in [`theme`](common-ui/src/main/java/com/suno/android/common_ui/theme/)
- Base composables in [`components`](common-ui/src/main/java/com/suno/android/common_ui/components/)
- Custom layouts in [`layouts`](common-ui/src/main/java/com/suno/android/common_ui/layouts/)
- Animation utilities in [`animations`](common-ui/src/main/java/com/suno/android/common_ui/animations/)

### Core Infrastructure

#### Common Core Utils (`common-core-utils/`)

Foundational utilities and base components.

**Resposibilities:**

- Global error handling
- App lifecycle management
- Shared preferences
- Base architecture components

**Key Classes:**

- [`TopLevelErrorManager`](common-core-utils/src/main/java/com/suno/android/common_core_utils/global_errors/TopLevelErrorManager.kt)
- [`AppLifecycleManager`](common-core-utils/src/main/java/com/suno/android/common_core_utils/helpers/AppLifecycleManager.kt)
- [`PrefsDataStoreManager`](common-core-utils/src/main/java/com/suno/android/common_core_utils/environment/PrefsDataStoreManager.kt)
- Base MVI components in [`mvi`](common-core-utils/src/main/java/com/suno/android/common_core_utils/mvi/)

#### Common Analytics (`common-analytics/`)

Analytics and tracking implementation.

**Resposibilities:**

- Event tracking
- User analytics
- Performance monitoring
- Crash reporting

**Key Classes:**

- [`AnalyticsManager`](common-analytics/src/main/java/com/suno/android/common_analytics/managers/AnalyticsManager.kt)
- Event trackers in [`trackers`](common-analytics/src/main/java/com/suno/android/common_analytics/trackers/)
- Custom analytics providers in [`providers`](common-analytics/src/main/java/com/suno/android/common_analytics/providers/)

#### Common i18n (`common-i18n/`)

Internationalization and localization.

**Resposibilities:**

- Language management
- Translations
- Locale-specific formatting

**Key Classes:**

- [`I18nManager`](common-i18n/src/main/java/com/suno/android/common_i18n/managers/I18nManager.kt)
- [`I18nModule`](common-i18n/src/main/java/com/suno/android/common_i18n/di/I18nModule.kt)

#### Common Gating (`common-gating/`)

Feature flagging system.

**Resposibilities:**

- Feature flag management
- A/B testing
- Experiment tracking

**Key Classes:**

- [`StatsigManager`](common-gating/src/main/java/com/suno/android/gating/StatsigManagerImpl.kt)
- Feature flag providers in [`providers`](common-gating/src/main/java/com/suno/android/gating/providers/)
- Experiment managers in [`experiments`](common-gating/src/main/java/com/suno/android/gating/experiments/)

## Technical Implementation Details

### Dependency Injection

- Hilt for DI throughout the app
- Module-level component providers
- Scoped dependencies management

### State Management

- MVI architecture pattern
- Kotlin Flow for reactive streams
- StateFlow for UI state
- SharedFlow for events

### Threading Model

- Coroutines for async operations
- CoroutineScope management
- Dispatchers usage patterns
- Background work handling

### Data Flow

```
UI Layer (Compose) → ViewModel → Repository → [Network/Database]
     ↑                   ↑          ↓              ↓
     └───────────── StateFlow ←─────┴──────────────┘
```

### Security Implementation

- Certificate pinning for network requests
- Encrypted preferences for sensitive data
- Token management for authentication
- ProGuard/R8 configuration

### Testing Strategy

- Unit tests: JUnit, Mockk
- UI tests: Compose testing
- Integration tests: Hilt testing
- Automated testing setup

### Performance Considerations

- Lazy loading patterns
- Memory management
- Background task optimization
- Image loading optimization