Quick Start Guide¶

This guide provides essential information for new developers to quickly get started with the DocuSnap-Frontend project.

Key Components and Files¶

1. Entry Points¶

MainActivity.kt: Main application entry point
Initializes the application
Sets up the navigation host
Configures dependencies
AppModule.kt: Dependency injection configuration
Provides application-wide dependencies
Configures services and repositories
Manages singleton instances

2. Core Modules¶

DocumentViewModel.kt: Core of document processing
Manages document state and operations
Handles document loading, saving, and updating
Coordinates with repositories for data operations
ImageProcessingViewModel.kt: Core of image processing
Manages image processing state and operations
Handles image filters and transformations
Coordinates with image processing services
BackendApiService.kt: Core of backend communication
Manages API requests and responses
Implements encryption and security
Handles error cases and retries

3. Data Models¶

Document.kt: Document data model
Defines document structure and properties
Used throughout the document processing flow
Form.kt: Form data model
Defines form structure and properties
Includes form fields and metadata
ExtractedInfoItem.kt: Extracted information model
Represents extracted text or field data
Used in both documents and forms

4. UI Components¶

screens/: Main screen implementations
Contains all application screens
Organized by feature or function
components/: Reusable UI components
Contains shared UI elements
Used across multiple screens
theme/: Application theme and styles
Defines colors, typography, and shapes
Configures Material Design theme

Development Environment Setup¶

1. Environment Requirements¶

Android Studio: Arctic Fox or higher
JDK: Version 11 or higher
Android SDK: API level 33 or higher
Gradle: Compatible with project configuration

2. Build Steps¶

Clone the Repository:

git clone https://github.com/JI-DeepSleep/DocuSnap-Frontend.git
cd DocuSnap-Frontend

Open in Android Studio:
Launch Android Studio
Select "Open an Existing Project"
Navigate to the cloned repository directory
Sync Gradle Files:
Wait for the automatic sync or
Click "Sync Project with Gradle Files" button
Build and Run:
Select a device or emulator
Click the "Run" button or press Shift+F10

3. Debugging Tips¶

Logcat: Use for viewing logs
Filter by tag to focus on specific components
Use different log levels (DEBUG, INFO, ERROR)
Layout Inspector: Debug UI issues
View component hierarchy
Inspect properties and constraints
Database Inspector: View database content
Examine tables and records
Execute SQL queries for testing
Network Profiler: Monitor network activity
Track API calls
Analyze response times and data sizes

Common Development Workflows¶

1. Adding a New Screen¶

Create a new Composable function in the screens/ directory:

@Composable
fun NewScreen(
    viewModel: SharedViewModel = hiltViewModel(),
    onNavigate: (String) -> Unit
) {
    // Screen implementation
}

Add a new route in the navigation package:

object Screen {
    // Existing routes
    object NewScreen : Screen("new_screen")
}

Register the screen in the NavHost:

NavHost(
    navController = navController,
    startDestination = startDestination
) {
    // Existing routes
    composable(Screen.NewScreen.route) {
        NewScreen(
            onNavigate = { route -> navController.navigate(route) }
        )
    }
}

2. Modifying Data Models¶

Update the data class definition:

@Serializable
data class Document(
    val id: String,
    val name: String,
    // Add new fields
    val newField: String? = null,
    // Other existing fields
)

Update corresponding database entity if needed:

@Entity(tableName = "documents")
data class DocumentEntity(
    @PrimaryKey val id: String,
    val name: String,
    // Add new column
    @ColumnInfo(name = "new_field") val newField: String?,
    // Other existing columns
)

Add database migration strategy:

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL("ALTER TABLE documents ADD COLUMN new_field TEXT")
    }
}

3. Adding New Functionality¶

Determine which module the functionality belongs to

Add necessary methods to the appropriate ViewModel:

// In DocumentViewModel
fun newFeature(param: String) {
    viewModelScope.launch {
        _isLoading.value = true
        try {
            val result = repository.performNewFeature(param)
            _featureResult.value = result
        } catch (e: Exception) {
            _error.value = "Error: ${e.message}"
        } finally {
            _isLoading.value = false
        }
    }
}

Update the UI to support the new feature:

@Composable
fun FeatureComponent(viewModel: DocumentViewModel) {
    val result by viewModel.featureResult.collectAsState()

    Column {
        Button(onClick = { viewModel.newFeature("param") }) {
            Text("Execute New Feature")
        }

        if (result != null) {
            Text("Result: $result")
        }
    }
}

Architecture Overview¶

DocuSnap-Frontend follows the MVVM (Model-View-ViewModel) architecture pattern:

Model: Data models and repositories
Represents the data and business logic
Handles data access and storage
View: Jetpack Compose UI components
Displays data to the user
Forwards user actions to the ViewModel
ViewModel: State management and business logic
Manages UI state
Processes user actions
Communicates with repositories

Data flows through the application in a unidirectional pattern: - User actions in the UI trigger ViewModel methods - ViewModel processes actions and updates state - UI automatically updates to reflect the new state

Common Pitfalls and Solutions¶

1. State Management¶

Pitfall: Mutable state shared across multiple components

Solution: Use StateFlow in ViewModels and collect at the UI level:

// In ViewModel
private val _state = MutableStateFlow(initialState)
val state: StateFlow<UiState> = _state.asStateFlow()

// In UI
val state by viewModel.state.collectAsState()

2. Coroutine Scope¶

Pitfall: Using the wrong coroutine scope or not cancelling coroutines

Solution: Use the appropriate scope and ensure proper cancellation:

// In ViewModel
viewModelScope.launch {
    // Long-running operation
}
// Automatically cancelled when ViewModel is cleared

// For background service
val job = CoroutineScope(Dispatchers.IO + SupervisorJob()).launch {
    // Background operation
}
// Remember to cancel: job.cancel()

3. Image Processing Performance¶

Pitfall: Performing heavy image processing on the main thread

Solution: Use background dispatchers and optimize processing:

viewModelScope.launch(Dispatchers.IO) {
    val processedBitmap = withContext(Dispatchers.Default) {
        // Heavy image processing
        imageProcService.processImage(bitmap)
    }

    // Update UI state on main thread
    _uiState.update { it.copy(editingBitmap = processedBitmap) }
}

4. Memory Management¶

Pitfall: Memory leaks from holding references to contexts or activities

Solution: Use application context, weak references, or lifecycle-aware components:

// Use application context for long-lived objects
val imageLoader = ImageLoader(context.applicationContext)

// Use rememberCoroutineScope in Compose
val scope = rememberCoroutineScope()

This quick start guide should help new developers understand the key components of DocuSnap-Frontend and get started with common development tasks. For more detailed information, refer to the specific documentation sections on architecture, modules, and processes.