# Yorvana — Project Overview & Context

Yorvana is a privacy-first Android application for logging vehicle maintenance and repair history. It prioritizes user data ownership by storing all records in an open, portable, and human-readable JSON format on the user's filesystem (the "Vault").

## 🚀 Quick Start

- **Build**: `./gradlew assembleDebug`
- **Run Unit/JVM Tests**: `./gradlew test`
- **Run All Tests & Coverage**: `./gradlew verifyWithCoverage`
- **Generate Store Screenshots (High-Fidelity)**: `./gradlew generateStoreScreenshots -PscreenshotBuild`
- **Update Screenshots**: `./gradlew recordRoborazziDebug`
- **Verify Screenshots**: `./gradlew verifyRoborazziDebug`

## 🛠 Tech Stack

- **Platform**: Android (Min SDK 26, Target SDK 36)
- **Language**: Kotlin (1.7+)
- **UI Framework**: Jetpack Compose (Material 3)
- **Navigation**: Navigation 3
- **Data Storage**: Plain JSON files (Kotlinx Serialization) + Android DataStore for app settings
- **File Access**: Storage Access Framework (SAF) via `DocumentFile`
- **Concurrency**: Kotlin Coroutines & Flow
- **Testing**:
    - **Functional**: Robolectric (JVM-based UI tests)
    - **Visual**: Roborazzi (Screenshot regression testing)
    - **Mocking**: MockK
    - **Assertions**: Google Truth
    - **Flow Testing**: Turbine

## 🏗 Architecture

The project follows a standard MVVM (Model-ViewModel-View) pattern combined with the Repository pattern.

### 1. Data Layer (`com.yorvana.data`)
- **Model**: Plain Kotlin data classes (`Vehicle`, `ServiceRecord`, `WorkItem`, `Category`).
- **Storage**: `VaultStorage` handles the low-level file I/O within the user's selected directory.
- **Repository**: Interfaces (`VehicleRepository`, `RecordRepository`, `CategoryRepository`) define data operations, with implementations (`...Impl`) managing data flow and denormalization logic (see ADR-008).

### 2. Domain Layer (`com.yorvana.domain`)
- Contains cross-cutting models like `VehicleWithMeta` and `RecordWithCategory` used to simplify UI rendering.

### 3. UI Layer (`com.yorvana.ui`)
- **Navigation**: Defined in `Screen.kt` and managed by `AppNavGraph.kt`.
- **ViewModels**: State management using `StateFlow`. Manual dependency injection via `ViewModelFactory`.
- **Composables**: Screens are organized by feature (e.g., `records`, `vehicles`, `settings`).

### 4. Initialization (`com.yorvana.YorvanaApplication`)
- Performs manual dependency injection and initializes core components like `VaultStorage` and `AppPreferences`.

## 📜 Development Conventions

- **Git Workflow**: Do not commit and push the changes under any circumstances unless explicitly asked by the user. The only exception is the Dependabot resolution process in `docs/dependabot-workflow.md`, which pre-authorizes mechanical auto-fix commits/pushes and allows manual fix commits/pushes after the documented review path is followed.
- **Data Integrity**: The app uses defensive reads and never silently overwrites files. All data files include a `schemaVersion`.
- **Performance**: Vehicle list loads are optimized to O(N vehicles) by denormalizing record counts and last service dates into `vehicle.json`.
- **Testing Strategy**:
    - Aim for high coverage using Robolectric tests in `src/test` for fast execution on the JVM.
    - Use Screenshot tests for all major screens and UI components.
- **Data Portability**: The folder structure is designed to be human-navigable.
    ```
    Yorvana/
    ├── categories.json
    └── vehicles/
        └── {vehicle-slug}/
            ├── vehicle.json
            └── records/
                ├── {uuid}.json
                └── {uuid}/ (attachments)
    ```

## 🔗 Key Documentation
- `docs/specs.md`: Detailed functional requirements and acceptance criteria.
- `docs/adr.md`: Architectural Decision Records explaining the "why" behind key technical choices.
- `docs/dependabot-workflow.md`: Standard procedure for resolving Dependabot PRs.