CardVault Android Development Rules

You are an expert Android developer building **CardVault**, an offline-first digital wallet application for managing credit cards, debit cards, gift cards, vouchers, memberships, and other card types.

Core Principles

1. **100% Offline Operation**: NEVER add network permissions, cloud APIs, or remote dependencies

2. **Privacy First**: No analytics, tracking, or data collection - reject any third-party telemetry

3. **Premium Experience**: All animations must target 60fps with smooth Material Design 3 transitions

4. **Local Storage Only**: All data stays on device in Room database and app's private storage

5. **Security**: Use Google Tink for encryption, sandboxed storage for all files

Technology Stack

Required Technologies

Build Configuration

Package Structure

```

com.technitedminds.wallet/

├── MainActivity.kt # @AndroidEntryPoint entry point

├── WalletApplication.kt # @HiltAndroidApp application class

├── data/ # Data layer implementations

│ ├── local/

│ │ ├── database/ # Room entities, DAOs, converters, WalletDatabase

│ │ ├── files/ # ImageFileManager for file operations

│ │ └── preferences/ # Proto DataStore managers

│ ├── repository/ # Repository implementations (*RepositoryImpl.kt)

│ ├── mapper/ # Entity ↔ Domain model mapping

│ └── ocr/ # ML Kit text recognition

├── domain/ # Business logic layer

│ ├── model/ # Domain models (Card, CardType, Category)

│ ├── repository/ # Repository interfaces

│ ├── usecase/ # Business logic use cases

│ └── util/ # Domain utilities

├── presentation/ # UI layer

│ ├── screens/ # Feature screens (*Screen.kt, *ViewModel.kt)

│ ├── components/ # Reusable composables

│ └── navigation/ # Navigation setup

├── di/ # Hilt modules (@Module, @InstallIn)

├── ui/theme/ # M3 theming (Color, Theme, Type)

└── utils/ # Extensions and utilities

```

Domain Models

Card Model

```kotlin

data class Card(

val id: Long = 0,

val name: String,

val type: CardType,

val categoryId: Long,

val imagePaths: List<String>, // Front and back image paths

val extractedData: Map<String, String>, // OCR results for textual cards

val customFields: Map<String, String>, // User-added fields

val gradient: CardGradient?, // For textual cards display

val createdAt: Long,

val updatedAt: Long

)

```

CardType Sealed Class

```kotlin

sealed class CardType {

object Credit : CardType() // OCR-enabled

object Debit : CardType() // OCR-enabled

object TransportCard : CardType() // Image-only

object GiftCard : CardType() // Image-only

object LoyaltyCard : CardType() // Image-only

object MembershipCard : CardType() // Image-only

// ... (and other image-only types)

}

```

Category Model

```kotlin

data class Category(

val id: Long = 0,

val name: String,

val iconResId: Int,

val colorHex: String,

val isDefault: Boolean

)

```

Card Workflows

Textual Cards (Credit/Debit Only)

1. User selects Credit or Debit card type

2. Camera captures front and back images

3. ML Kit OCR extracts: card number, expiry date, CVV, cardholder name

4. User reviews and edits extracted data

5. System generates gradient card design for sharing

6. Images stored, card saved to database

Image-Only Cards (All Other Types)

1. User selects card type (Gift, Voucher, Membership, etc.)

2. Camera captures front and back images

3. **No OCR processing** - pure image storage

4. User adds custom fields if needed

5. Images stored as-is for sharing

6. Card saved to database

Code Style & Naming Conventions

File Naming

Kotlin Style

Compose Best Practices

ViewModel Patterns

Repository Implementation

Use Case Guidelines

UI/UX Requirements

Performance Targets

Animation Standards

Material Design 3

Camera & OCR Implementation

Camera

OCR Processing

Data Management

Room Database

Image Storage

Proto DataStore

Dependency Injection (Hilt)

Module Structure

Common Annotations

Navigation

Structure

Example Destinations

```kotlin

sealed interface NavigationDestination {

@Serializable object Home

@Serializable object Categories

@Serializable object Settings

@Serializable data class AddCard(val cardType: CardType? = null)

@Serializable data class CardDetail(val cardId: Long)

@Serializable data class Camera(val captureMode: CaptureMode)

}

```

Security Requirements

Common Pitfalls to Avoid

Testing Guidelines

Unit Tests

Integration Tests

UI Tests

Implementation Process

When implementing new features:

1. **Start with domain layer**: Define models, repository interface, use case

2. **Implement data layer**: Create entity, DAO, repository implementation, mapper

3. **Create ViewModel**: Set up state management with StateFlow/SharedFlow

4. **Build composable UI**: Implement screen with proper state hoisting

5. **Wire up Hilt**: Add necessary modules and injection points

6. **Add navigation**: Define route and integrate with NavHost

7. **Test thoroughly**: Write unit tests, integration tests, UI tests

8. **Verify performance**: Ensure 60fps animations and smooth interactions

Debugging Commands

```bash

Build debug APK

./gradlew assembleDebug

Install and run

./gradlew installDebug

Run unit tests

./gradlew test

Run instrumented tests

./gradlew connectedAndroidTest

Generate KSP sources (for Room, Hilt)

./gradlew kspDebugKotlin

Clean build

./gradlew clean

```

Critical Reminders