# kashif-e/kollama architecture

> Architecture diagram of the GitHub repository kashif-e/kollama, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kashif-e/kollama
- Repository: https://github.com/kashif-e/kollama

## Overview

##### Project Type & Purpose
- Kollama is a **client-side**, full-stack application in the sense that it runs entirely locally on multiple platforms (Android, iOS, Desktop JVM, Web, Native).
- Its purpose is to provide a polished chat UI for interacting with local Ollama AI models, with persistence (SQLDelight) and real-time streaming.

##### File Structure & Architecture
- Top-level modules:
- `composeApp/` – Kotlin Multiplatform module (commonMain + androidMain, iosMain, jvmMain, jsMain, nativeMain) containing UI, domain, data layers.
- `iosApp/` – Xcode project that depends on the KMP framework produced by `composeApp`.
- Layers inside `composeApp/src/commonMain`:
a. **presentation/** – Composables, ViewModel, state, theme, modifiers
b. **domain/** – Interfaces and domain models
c. **data/** – Repositories, service wrappers (`OllamaService`), DB wrappers (`Database`)
d. **di/** – Koin modules
- Platform-specific source sets provide implementations for the service (HTTP via Ktor) and database (SQLDelight drivers).

##### README Architecture Section
- Confirms **Clean Architecture**: Presentation → Domain → Data → Infrastructure.
- Key technologies: Kotlin Multiplatform, Compose MPP, SQLDelight, Ktor, Koin

##### Main Components & Relationships
- **Client Apps (Platform Targets)**
- Android App (AndroidManifest & androidMain)
- iOS App (Xcode/iosApp)
- Desktop JVM (jvmMain)
- Web (jsMain + webpack)
- Native binaries (nativeMain)
- **Shared KMP Framework**
- Presentation Layer
- Domain Layer
- Data Layer
- DI Module
- **External Systems**
- Local Ollama server (HTTP API at localhost:11434)
- Local database (SQLDelight engine per platform)

##### Interactions & Data Flows
- **User Interaction** → Composables (`ChatScreen`, UI components)
→ `ChatViewModel` (state management, Kotlin Flow)
→ Domain interfaces (`ChatRepository`)
→ Data implementation (`ChatRepositoryImpl`)
→ a) **OllamaService**: streams requests/responses to local Ollama server
b) **DatabaseWrapper**: reads/writes chat history via SQLDelight
- **Job Management**: `ChatJobManager` handles concurrent sessions, LRU caching
- **DI**: Koin provides repository, service, database, ViewModel injection

##### Architectural Patterns & Principles
- **Clean Architecture**: strict dependency direction (presentation → domain → data → infra)
- **Kotlin Multiplatform**: share core logic, customize per-platform drivers
- **Compose Multiplatform**: single UI codebase for all targets
- **Reactive State**: Kotlin Flow, remember/derivedStateOf for recomposition
- **LRU Caching**: ChatJobManager for session lifecycle

##### Final Checklist
- [ ] Layers clearly separated (Client Platforms, Presentation, Domain, Data, Infra)
- [ ] Components labeled (ViewModel, Repository, Services, DB)
- [ ] External Ollama server and local DB drawn at Infra layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Platforms"
        Android["Android App"]:::platform
        iOS["iOS App"]:::platform
        Desktop["Desktop JVM"]:::platform
        Web["Web (JS)"]:::platform
        Native["Native Binary"]:::platform
    end

    subgraph "Shared KMP Module"
        subgraph "Presentation Layer"
            ChatScreen["ChatScreen"]:::ui
            UIComponents["UI Components"]:::ui
            ChatViewModel["ChatViewModel"]:::ui
            ChatState["ChatState"]:::ui
            ChatEvent["ChatEvent"]:::ui
            JobManager["JobManager"]:::ui
        end
        subgraph "Domain Layer"
            ChatRepoInterface["ChatRepository (interface)"]:::domain
            ChatMsgModel["ChatMessageDomainModel"]:::domain
            ChatSessionModel["ChatSessionDomainModel"]:::domain
        end
        subgraph "Data Layer"
            ChatRepoImpl["ChatRepositoryImpl"]:::data
            OllamaService["OllamaService"]:::data
            DatabaseWrapper["Database"]:::data
            ChatDBSchema["ChatDatabase.sq"]:::data
        end
        subgraph "DI Module"
            AppModule["AppModule"]:::di
        end
    end

    subgraph "Infrastructure"
        OllamaServer["Ollama Server"]:::infra
        LocalDB["Local DB"]:::infra
    end

    Android --> ChatScreen
    iOS --> ChatScreen
    Desktop --> ChatScreen
    Web --> ChatScreen
    Native --> ChatScreen

    ChatScreen --> ChatViewModel
    ChatViewModel --> ChatRepoInterface
    ChatViewModel --> JobManager
    ChatRepoInterface --> ChatRepoImpl
    AppModule --> ChatViewModel
    AppModule --> ChatRepoImpl

    ChatRepoImpl --> OllamaService
    ChatRepoImpl --> DatabaseWrapper

    OllamaService -->|"HTTP/JSON"| OllamaServer
    DatabaseWrapper -->|"SQLDelight"| LocalDB

    click ChatScreen "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/presentation/ChatScreen.kt"
    click UIComponents "https://github.com/kashif-e/kollama/tree/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/presentation/components"
    click ChatViewModel "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/presentation/state/ChatViewModel.kt"
    click ChatState "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/presentation/state/ChatState.kt"
    click ChatEvent "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/presentation/state/ChatEvent.kt"

    click ChatRepoInterface "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/domain/interfaces/ChatRepository.kt"
    click ChatMsgModel "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/domain/model/ChatMessageDomainModel.kt"
    click ChatSessionModel "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/domain/model/ChatSessionDomainModel.kt"

    click ChatRepoImpl "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/data/repository/ChatRepository.kt"
    click OllamaService "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/data/local/service/OllamaService.kt"
    click DatabaseWrapper "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/data/local/database/Database.kt"
    click ChatDBSchema "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/sqldelight/com/kashif/kollama/ChatDatabase.sq"

    click AppModule "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/di/AppModule.kt"
    click JobManager "https://github.com/kashif-e/kollama/blob/main/composeApp/src/commonMain/kotlin/com/kashif/kollama/presentation/utils/JobManager.kt"

    click Android "https://github.com/kashif-e/kollama/blob/main/composeApp/src/androidMain/AndroidManifest.xml"
    click iOS "https://github.com/kashif-e/kollama/blob/main/iosApp/iosApp.xcodeproj"
    click Desktop "https://github.com/kashif-e/kollama/blob/main/composeApp/src/jvmMain/kotlin/main.kt"
    click Web "https://github.com/kashif-e/kollama/blob/main/composeApp/src/jsMain/resources/index.html"
    click Native "https://github.com/kashif-e/kollama/blob/main/composeApp/src/nativeMain/kotlin/com/kashif/kollama/data/local/service/OllamaService.native.kt"

    classDef platform fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef ui fill:#CCEBFF,stroke:#333,stroke-width:1px
    classDef domain fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef data fill:#FFD9B3,stroke:#333,stroke-width:1px
    classDef infra fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef di fill:#EAD1DC,stroke:#333,stroke-width:1px
```
