# kwila-cloud/karriba architecture

> Architecture diagram of the GitHub repository kwila-cloud/karriba, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kwila-cloud/karriba
- Repository: https://github.com/kwila-cloud/karriba

## Overview

##### Project Type & Purpose
- Karriba is an open-source, offline-first, commercial drone record-keeping system. Its initial MVP focuses on an offline Android mobile app built with Flutter. The long-term vision includes both a cloud service and self-hosted deployment options.
- The README emphasizes data sovereignty, local-first operation, and scalability toward cloud synchronization in later stages.

##### File Structure
- The primary codebase is under the “app” directory. Notice the Flutter-specific files:
– The “lib” folder contains Dart source files. It is organized into multiple domain-specific modules (e.g., applicators, customers, pesticides, records) each with their own data access objects (DAOs) and corresponding pages.
– The “android” directory holds all the native Android configuration files, which confirms that the MVP is an Android app.
- The existence of configuration files (pubspec.yaml, analysis_options.yaml, etc.) and CI workflows (under .github/workflows) indicate standard development, build automation, and deployment setups.

##### Architectural Components
a. Mobile Client (Flutter Application)
– UI Layer: Represented by various pages (e.g., applicators_page.dart, customers_page.dart, pesticides_page.dart, records_page.dart). Include elements like the main.dart and supporting UI components (e.g., coming_soon_dialog.dart, unsaved_changes_dialog.dart).
– Business Logic Layer: This involves the controllers and page managers coordinating the user input with backend operations.
– Data Access Layer: Indicated by Dart files ending with “_dao.dart” (e.g., applicator_dao.dart, customer_dao.dart, pesticide_dao.dart, records_dao.dart). There’s also a database_helper.dart that suggests management of local storage.
b. Local Storage Component
– Although not explicitly detailed, the presence of DAO files and a “database_helper.dart” implies an underlying local database (for instance, SQLite) that stores drone records. Mark this component as the “Local Database” for offline-first functionality.
c. Data Synchronization/Cloud Service (Future Component)
d. External Services and CI/CD Tools
– Optionally annotate external services for cloud hosting that eventually might interact with the mobile client.

##### Relationships and Interactions Between Components
- CI/CD pipelines connecting to the code repository and build/deployment automation.

##### Architectural Patterns & Design Principles
- Separation of concerns:
– Clear distinction between UI, logic, and data.
– Offline-first design pattern that ensures functionality without internet connectivity.
- That the application uses Data Access Objects (DAOs) to encapsulate database interactions.
- Recognize the modular structure (separate files and modules for different record types like customers, applicators, pesticides, records) which simplifies maintenance and scalability.

##### Essential Elements
- For example, “User Input” → “UI Layer” → “Business Logic” → “Data Access Layer” → “Local Database.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Mobile Client Node
    MC["Mobile Client (Flutter)"]:::mobile
    click MC "https://github.com/kwila-cloud/karriba/tree/main/app/"

    %% Subgraphs for Mobile Client Components
    subgraph "UI Layer"
        U1["Main Page (main.dart)"]:::ui
        click U1 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/main.dart"
        U2["Applicators Page"]:::ui
        click U2 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/applicators_page.dart"
        U3["Customers Page"]:::ui
        click U3 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/customers_page.dart"
        U4["Pesticides Page"]:::ui
        click U4 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/pesticides_page.dart"
        U5["Records Page"]:::ui
        click U5 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/records_page.dart"
        U6["Coming Soon Dialog"]:::ui
        click U6 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/coming_soon_dialog.dart"
        U7["Unsaved Changes Dialog"]:::ui
        click U7 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/unsaved_changes_dialog.dart"
    end

    subgraph "Business Logic Layer"
        B1["Core Controller (main.dart)"]:::logic
        click B1 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/main.dart"
    end

    subgraph "Data Access Layer"
        D1["Applicator DAO"]:::dao
        click D1 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/applicator_dao.dart"
        D2["Customer DAO"]:::dao
        click D2 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/customer_dao.dart"
        D3["Pesticide DAO"]:::dao
        click D3 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/pesticide/pesticide_dao.dart"
        D4["Records DAO"]:::dao
        click D4 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/records_dao.dart"
        D5["Record Pesticide DAO"]:::dao
        click D5 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/record_pesticide/record_pesticide_dao.dart"
        D6["Database Helper"]:::dao
        click D6 "https://github.com/kwila-cloud/karriba/blob/main/app/lib/database_helper.dart"
    end

    %% External Components
    LDB["Local Database"]:::db
    CS["Cloud Sync Module [Future]"]:::future

    subgraph "CI/CD Pipeline"
        C1["Flutter Build APK Workflow"]:::cicd
        click C1 "https://github.com/kwila-cloud/karriba/blob/main/.github/workflows/flutter_build_apk.yml"
        C2["Comment Artifact URL on PR Workflow"]:::cicd
        click C2 "https://github.com/kwila-cloud/karriba/blob/main/.github/workflows/comment_artifact_url_on_pr.yml"
    end

    %% Relationships
    MC -->|"launches"| U1
    U1 -->|"triggers"| B1
    B1 -->|"calls"| D6
    D6 -->|"accesses"| LDB
    LDB <==>|"syncs"| CS
    MC ---|"CI/CD triggers"| C1

    %% Styles
    classDef mobile fill:#a7d8de,stroke:#333,stroke-width:2px;
    classDef ui fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef logic fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef dao fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef db fill:#f1948a,stroke:#333,stroke-width:2px,font-style:italic;
    classDef cicd fill:#d7bde2,stroke:#333,stroke-width:2px;
    classDef future fill:#ffcc80,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
```
