# kiln-ai/kiln architecture

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

- Interactive diagram: https://gitdiagram.com/kiln-ai/kiln
- Repository: https://github.com/kiln-ai/kiln

## Overview

##### Detailing Each Component
A. Desktop App:
- Represented as its own client layer.
- Internal scripts (e.g., desktop_server.py, dev_server.py) and build scripts for packaging (WinInnoSetup.iss, build scripts).
- That the desktop apps target Windows, MacOS, and Linux.

B. Web UI:
- Folder “app/web_ui” with its Svelte-based structure.
- That it communicates with backend REST APIs.

C. Backend/API Server:
- REST API server (from libs/server/kiln_server) that handles requests related to projects, tasks, prompts, runs, and custom errors.
- That the server may also interface with the core logic library.

D. Core Business Logic (Library):
- Adapters (for fine-tune, eval, data generation, repair, parsers, and model adapters)
- Data Model (datamodel directory – handling projects, tasks, prompts, evaluations, dataset splits, etc.)
- Utilities (configuration, error handling, dataset import, formatting, etc.)
- This component is used by both the backend API (serving requests) and the desktop/web apps to process and validate data.

E. External Providers & Integrations:

##### Relationships and Data Flows
- That the Core Library “Adapter” layer bridges to External Services and providers.
- Bi-directional communication where needed (e.g., updating datasets, receiving model predictions).

##### Architectural Patterns and Design Principles
- Separation of concerns:
- UI clients (Desktop/Web) handle presentation and then call APIs.
- The API Server mediates client requests and orchestrates business logic.
- The Core Library encapsulates domain-specific operations (adapters, fine-tuning, evaluation, etc.).
- Multi-platform deployment for desktop apps and the modular design (adapter registry, parser registry, etc.) indicating a plug-in architecture.
- Testing structure by noting the “test_…” files within the desktop and core directories (showing a commitment to quality).

##### Technology Stack and Frameworks
- Next to each component, annotate the primary technologies:
- Desktop App: Python with custom scripts, packaging with WinInnoSetup, and shell scripts.
- Web UI: Svelte, TypeScript, Vite, Tailwind CSS, ESLint/Prettier for formatting.
- API Server: Python, FastAPI style server (if inferred from the structure), Uvicorn (indicated by uv.lock), and REST API endpoints.
- Core Library: Pure Python, modular structure for AI prototyping (adapters, data models).

##### Final Touches
- Every element is well annotated with brief text describing its role (e.g., “Core Business Logic: handles evaluations, fine-tuning, and data formatting”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        DesktopApp["Desktop Application Component\n(Python, packaging with WinInnoSetup)"]:::client
        WebUI["Web UI Component\n(Svelte, TypeScript, Vite, Tailwind)"]:::client
    end

    %% Server Layer
    subgraph "Server Layer"
        APIServer["Backend/API Server Component\n(FastAPI, Uvicorn, REST endpoints)"]:::backend
        subgraph "Core Business Logic & Libraries"
            Adapters["Adapters\n(fine_tune, eval, data generation, repair, parsers)"]:::core
            DataModels["Data Models\n(projects, tasks, prompts, evaluations, dataset splits)"]:::core
            Utilities["Utilities\n(configuration, error handling, dataset import, formatting)"]:::core
        end
    end

    %% External Systems
    subgraph "External Systems"
        ExternalProviders["External Services & Providers\n(Ollama, OpenAI, AWS, etc.)"]:::external
        DatasetCollaboration["Collaboration & Git-backed Dataset Storage"]:::collab
    end

    %% Data Flow Connections
    DesktopApp -->|"REST_API_Calls"| APIServer
    WebUI -->|"REST_API_Calls"| APIServer
    APIServer -->|"BusinessLogic"| Adapters
    DesktopApp -->|"Local_Processing"| DataModels
    Adapters -->|"AdapterCalls"| ExternalProviders
    APIServer -->|"DataSync"| DatasetCollaboration
    WebUI -->|"DataSync"| DatasetCollaboration

    %% Styles
    classDef client fill:#a5f9d6,stroke:#333,stroke-width:2px;
    classDef backend fill:#d6a5f9,stroke:#333,stroke-width:2px;
    classDef core fill:#f9a5d6,stroke:#333,stroke-width:2px;
    classDef external fill:#d6f9a5,stroke:#333,stroke-width:2px;
    classDef collab fill:#faf9a5,stroke:#333,stroke-width:2px;

    %% Click Events
    click DesktopApp "https://github.com/kiln-ai/kiln/tree/main/app/desktop"
    click WebUI "https://github.com/kiln-ai/kiln/tree/main/app/web_ui"
    click APIServer "https://github.com/kiln-ai/kiln/tree/main/libs/server/kiln_server"
    click Adapters "https://github.com/kiln-ai/kiln/tree/main/libs/core/kiln_ai"
    click DataModels "https://github.com/kiln-ai/kiln/tree/main/libs/core/kiln_ai"
    click Utilities "https://github.com/kiln-ai/kiln/tree/main/libs/core/kiln_ai"
```
