Dev: Building the Application

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• ROADMAP.md
• app/src/main/AndroidManifest.xml
• app/src/main/java/com/musagenius/ocrapp/MainActivity.kt
• app/src/main/java/com/musagenius/ocrapp/di/AppModule.kt
• app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt
• app/src/main/assets/tessdata/README.md
• app/src/main/java/com/musagenius/ocrapp/presentation/viewmodel/OCRViewModel.kt

Introduction

This document provides a technical overview of the project structure, architecture, and core dependencies for the Material Expressive Android OCR App. The application is an offline-first tool for extracting text from images, built with a modern Android technology stack. It is designed to be maintainable and scalable, following Clean Architecture principles.

The project utilizes Jetpack Compose for the UI, Tesseract for offline OCR, CameraX for image capture, Room for local persistence, and Hilt for dependency injection. This guide is intended for developers to understand the foundational components and how they interact to build, run, and extend the application.

Sources: README.md, ROADMAP.md

Architecture

The application is built using an MVVM (Model-View-ViewModel) pattern combined with the principles of Clean Architecture. This separates concerns into distinct layers, promoting testability and maintainability.

Sources: README.md, ROADMAP.md

Architectural Layers

The following diagram illustrates the three primary layers of the application's architecture.

This diagram shows the dependency flow from the UI down to the data sources.

• Presentation Layer: Contains the UI (built with Jetpack Compose) and ViewModels. The UI observes state from the ViewModels and forwards user events. The MainActivity and various screen composables like OCRResultScreen reside here.
• Domain Layer: This is the core business logic layer. It is independent of any framework. It contains Use Cases (e.g., ProcessImageUseCase, DeleteLanguageUseCase), domain models (e.g., ScanResult), and repository interfaces.
• Data Layer: Responsible for providing data to the domain layer. It contains implementations of the repository interfaces, and manages data sources like the Room database and the Tesseract-based OCRServiceImpl.

Sources: README.md, ROADMAP.md, app/src/main/java/com/musagenius/ocrapp/MainActivity.kt, app/src/main/java/com/musagenius/ocrapp/domain/usecase/DeleteLanguageUseCase.kt, app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt

Technology Stack & Dependencies

The project is built on a modern Android technology stack, emphasizing offline-first functionality and a declarative UI.

Technology	Purpose	Source
Kotlin + Coroutines	Primary language and asynchronous programming.	README.md
Jetpack Compose	Declarative UI toolkit for building the user interface.	README.md
Material Design 3	The design system used for UI components and theming.	README.md, app/src/main/java/com/musagenius/ocrapp/presentation/ui/theme/Color.kt
Tesseract (tess-two)	The core offline OCR engine.	README.md, app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt
CameraX	Jetpack library for camera integration and image capture.	README.md
Room	Jetpack library for local database persistence (SQLite).	README.md
Hilt	Jetpack library for dependency injection.	README.md, app/src/main/java/com/musagenius/ocrapp/di/AppModule.kt
Navigation Compose	For navigating between composable screens.	app/src/main/java/com/musagenius/ocrapp/MainActivity.kt:25-30

Dependency Injection with Hilt

Dependency injection is managed by Hilt, which simplifies DI in Android applications. The setup involves annotating the Application class, Activities, and ViewModels, and creating modules to provide dependencies.

Sources: app/src/main/java/com/musagenius/ocrapp/di/AppModule.kt, app/src/main/java/com/musagenius/ocrapp/MainActivity.kt

Core Application Module

The AppModule provides application-wide singleton dependencies, such as the application context and coroutine dispatchers.

// app/src/main/java/com/musagenius/ocrapp/di/AppModule.kt

@Module
@InstallIn(SingletonComponent::class)
object AppModule {

    @Provides
    @Singleton
    fun provideApplicationContext(@ApplicationContext context: Context): Context {
        return context
    }

    @Provides
    @Singleton
    @IoDispatcher
    fun provideIoDispatcher(): CoroutineDispatcher = Dispatchers.IO

    // ... other dispatchers
}

Sources: app/src/main/java/com/musagenius/ocrapp/di/AppModule.kt:13-30

DI Flow

The diagram below shows how Hilt provides dependencies to different parts of the application.

This diagram illustrates Hilt's role in wiring together the application's components.

Sources: app/src/main/java/com/musagenius/ocrapp/di/AppModule.kt, app/src/main/java/com/musagenius/ocrapp/MainActivity.kt, app/src/main/java/com/musagenius/ocrapp/presentation/viewmodel/OCRViewModel.kt, TODO.md

Core Systems

OCR Processing

The core OCR functionality is encapsulated in OCRServiceImpl, which is a thread-safe wrapper around the Tesseract TessBaseAPI.

Key features of OCRServiceImpl:

• Thread Safety: A Mutex is used to serialize access to the TessBaseAPI, which is not thread-safe.
• Initialization: On first use for a specific language, it checks if the .traineddata file exists in the app's storage. If not, it copies it from the assets/tessdata directory.
• Image Preprocessing: It utilizes an ImagePreprocessor to enhance the image before running OCR, improving accuracy.
• Progress Tracking: The recognizeTextWithProgress function provides a Flow of progress updates for long-running OCR tasks.

Sources: app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt, app/src/main/assets/tessdata/README.md

The following sequence diagram shows the flow of processing an image.

This diagram details the interaction from a user event down to the Tesseract API call and back.

Sources: app/src/main/java/com/musagenius/ocrapp/presentation/ui/ocr/OCRResultScreen.kt, app/src/main/java/com/musagenius/ocrapp/presentation/viewmodel/OCRViewModel.kt, app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt

UI and Navigation

The application uses a single-activity architecture with MainActivity as the entry point. Navigation between screens is handled by Jetpack Navigation for Compose.

The main navigation graph is defined in MainActivity.kt and includes routes for the camera, image editor, and results screens.

This flow shows the primary user paths for capturing or selecting an image and viewing the OCR results.

Sources: app/src/main/java/com/musagenius/ocrapp/MainActivity.kt:42-108

Permissions

The application requires several permissions to function correctly, which are declared in the AndroidManifest.xml.

Permission	Max SDK Version	Purpose
android.permission.CAMERA	-	To access the device camera for scanning documents.
android.permission.READ_EXTERNAL_STORAGE	32	To read images from shared storage on older Android versions.
android.permission.WRITE_EXTERNAL_STORAGE	28	To save files on older Android versions.
android.permission.READ_MEDIA_IMAGES	-	To read images from the media store on Android 13+.

Additionally, the manifest declares required hardware features like android.hardware.camera. A FileProvider is also configured to securely share files with other apps.

Sources: app/src/main/AndroidManifest.xml:5-18, 33-40

Conclusion

The application is built upon a solid foundation of modern Android development practices. The use of Clean Architecture, Hilt, and Jetpack libraries ensures a decoupled, testable, and maintainable codebase. This structure allows for systematic implementation of features as outlined in the project's ROADMAP.md, such as building out the database layer, camera controls, and advanced OCR processing pipelines. Developers should adhere to these established patterns when contributing to the project.

Sources: README.md, ROADMAP.md