# icure/kraken-lite architecture

> Architecture diagram of the GitHub repository icure/kraken-lite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/icure/kraken-lite
- Repository: https://github.com/icure/kraken-lite

## Overview

##### Project Type and Purpose
- Kraken Lite is a lightweight, open-source back-end service built with Kotlin and Spring Boot.
- It exposes REST endpoints (v1/v2) for CRUD operations on health-care entities, backed by CouchDB and optional object-storage modules (SAM, Kmehr).
- It ships as a fat JAR (lite-core) and can be run standalone, via Docker, or with Docker Compose (CouchDB, booster, etc.).

##### File-Structure Analysis
- Top-level:
- compose/… ─ Docker Compose definitions for CouchDB and “cardinal-deployment.”
- booster/ ─ Preloader JAR + Dockerfile to speed up Spring Boot startup
- lite-core/ ─ Core Spring Boot application (Kotlin)
- buildSrc/ ─ Custom Gradle tasks (start/clean CouchDB, Docker utils)
- kraken-common (Git submodule) and gradle wrappers/configs
- Inside lite-core/src/main/kotlin/org/taktik/icure:
- asyncdao/ ─ DAO implementations against CouchDB (async)
- asynclogic/ ─ Business logic layer
- asyncservice/ ─ Service layer that orchestrates DAO + logic
- services/external/rest/lite/v1/v2/controllers ─ HTTP controllers
- config/, security/, cache/, properties/ ─ Spring configuration modules
- entities/, errors/, spring/asynccache/ ─ Domain models, error handlers, caching

##### README Insights
- Describes runtime properties for:
- CouchDB partitioning, view indexing (background/foreground)
- Authentication endpoints (JWT, HCP-only)
- Optional SAM/Kmehr modules (region flags, Spring profiles)
- External design-docs (signed CouchDB views)
- Plugin loading from external JAR folder

##### Main Components
a. HTTP API Layer
- Spring Boot embedded Tomcat + controllers (v1/v2).
- Booster preloader (optional entrypoint to accelerate app startup).
b. Service Layer
- asyncservice implementations
- Orchestrates calls to business logic and DAO.
c. Business-Logic Layer
- asynclogic implementations (validation, object-storage adapters).
d. Data-Access Layer
- asyncdao for CouchDB (Dispatcher, DAO interfaces, implementations).
- ObjectStorage DAOs (migration, tasks).
e. CouchDB Cluster
- Single or multi-node CouchDB (with partitions: default, Maurice, etc.)
- External views loader (via Git URLs + signing key).
f. Optional Modules
- SAM module (drug database)
- Kmehr module
- Plugin folder (custom JARs)
g. Infrastructure
- Docker Compose services (CouchDB container, booster container)
- Gradle build tasks

##### Relationships & Data Flow
- Client → HTTP(S) Load Balancer → (Booster) → Spring Boot Controllers
- Controller → Service → Logic → DAO → CouchDB
- CouchDB ↔ asyncview indexers (background or forced foreground)
- ObjectStorage client ↔ local FS or remote Icure cloud storage
- External View Loader fetches design-docs at startup
- Plugins folder scanned at startup and wired into Spring context

##### Architectural Patterns & Principles
- Layered architecture (Controller → Service → Logic → DAO)
- Asynchronous/non-blocking I/O for CouchDB calls
- Spring Boot auto-configuration (profiles, property overrides)
- Plugin-based extensibility (SAM, Kmehr, user plugins)
- Git-submodule for common mappers/generators (kraken-common)

##### Technologies & Frameworks
- Kotlin + Spring Boot (web, security, config)
- CouchDB (NoSQL, partitions, design Docs)
- WebSocket handler (for real-time operations)
- Docker & Docker-Compose (in compose/)
- Gradle Kotlin DSL (buildSrc custom tasks)
- Caffeine cache (async map cache)
- JWT for authentication

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actor
    Client["Client"]:::external
    LB["Load Balancer"]:::infra

    %% HTTP API Layer
    subgraph "HTTP API Layer"
        ControllersV1["REST Controllers v1"]:::api
        ControllersV2["REST Controllers v2"]:::api
        WSHandler["WebSocket Handler"]:::api
        Booster["Booster Preloader"]:::infra
    end

    %% Service Layer
    subgraph "Service Layer"
        ServiceIF["asyncservice Interfaces"]:::service
        ServiceImpl["asyncservice Implementations"]:::service
    end

    %% Logic Layer
    subgraph "Logic Layer"
        LogicIF["asynclogic Interfaces"]:::logic
        LogicImpl["asynclogic Implementations"]:::logic
        LogicObj["asynclogic ObjectStorage"]:::logic
    end

    %% DAO Layer
    subgraph "DAO Layer"
        DAOIF["asyncdao Interfaces"]:::db
        DAOImpl["asyncdao Implementations"]:::db
        DAOObjIF["ObjectStorage DAO Interfaces"]:::db
        DAOObjImpl["ObjectStorage DAO Impl"]:::db
    end

    %% Persistence & External
    CouchDB["CouchDB Cluster\n(partitions, views)"]:::infra
    ExtViewLoader["External View Loader"]:::infra
    ObjectStorage["ObjectStorage\n(Local FS / Cloud)"]:::db

    %% Plugins & Config
    PluginFolder["Plugin Folder\n(SAM/Kmehr/User)"]:::plugin
    PluginsManager["Plugin Manager"]:::plugin
    Config["Spring Config Modules"]:::infra
    Cache["Cache Layer (async cache)"]:::db
    Security["Security & JWT"]:::infra
    KrakenCommon["kraken-common Submodule"]:::infra

    %% Infra & Build
    GradleTasks["Gradle Custom Tasks"]:::infra

    %% Relationships
    Client -->|"HTTP/JSON"| LB
    LB -->|"optional"| Booster
    Booster -->|HTTP/JSON| ControllersV1
    Booster -->|HTTP/JSON| ControllersV2
    ControllersV1 -->|calls| ServiceIF
    ControllersV2 -->|calls| ServiceIF
    WSHandler -->|WebSocket| ServiceIF

    ServiceIF -->|orchestrates| LogicIF
    ServiceImpl -->|orchestrates| LogicImpl
    LogicIF -->|validates/adapts| DAOIF
    LogicObj -->|object storage| DAOObjIF

    DAOIF -->|CouchDB REST API| CouchDB
    DAOImpl -->|CouchDB REST API| CouchDB
    DAOObjIF -->|push/pull| ObjectStorage
    DAOObjImpl -->|push/pull| ObjectStorage

    ExtViewLoader -->|"loads design-docs"| CouchDB
    PluginFolder -->|scanned by| PluginsManager
    PluginsManager -->|wired into| ServiceIF

    Config -->|configures| ControllersV1
    Config -->|configures| ServiceIF
    Config -->|configures| LogicIF
    Config -->|configures| DAOIF

    Cache -->|caching| ServiceIF
    Security -->|auth/JWT| ControllersV1

    KrakenCommon -->|shared mappers| ServiceIF
    GradleTasks -->|manages lifecycle| CouchDB
    GradleTasks -->|manages lifecycle| Booster

    %% Click Events
    click ControllersV1 "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/services/external/rest/lite/v1/controllers"
    click ControllersV2 "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/services/external/rest/lite/v2/controllers"
    click WSHandler "https://github.com/icure/kraken-lite/blob/main/lite-core/src/main/kotlin/org/taktik/icure/services/external/http/WebSocketOperationHandler.kt"
    click Booster "https://github.com/icure/kraken-lite/tree/main/booster/Dockerfile"
    click ServiceIF "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/asyncservice"
    click ServiceImpl "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/asyncservice/impl"
    click LogicIF "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/asynclogic"
    click LogicImpl "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/asynclogic/impl"
    click LogicObj "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/asynclogic/objectstorage"
    click DAOIF "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/asyncdao"
    click DAOImpl "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/asyncdao/impl"
    click DAOObjIF "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/asyncdao/objectstorage"
    click DAOObjImpl "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/asyncdao/objectstorage/impl"
    click ExtViewLoader "https://github.com/icure/kraken-lite/blob/main/lite-core/src/main/kotlin/org/taktik/icure/config/ExternalViewsConfig.kt"
    click PluginsManager "https://github.com/icure/kraken-lite/blob/main/lite-core/src/main/kotlin/org/taktik/icure/config/PluginsManager.kt"
    click Config "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/config"
    click Cache "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/spring/asynccache"
    click Security "https://github.com/icure/kraken-lite/tree/main/lite-core/src/main/kotlin/org/taktik/icure/security"
    click KrakenCommon "https://github.com/icure/kraken-lite/tree/main/kraken-common"
    click GradleTasks "https://github.com/icure/kraken-lite/blob/main/buildSrc/src/main/kotlin/org/icure/task/CleanCouchDockerTask.kt"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#000;
    classDef service fill:#90EE90,stroke:#000;
    classDef logic fill:#98FB98,stroke:#000;
    classDef db fill:#FFA500,stroke:#000;
    classDef infra fill:#D3D3D3,stroke:#000;
    classDef plugin fill:#DDA0DD,stroke:#000;
    classDef external fill:#FFFFFF,stroke:#000;
```
