# kapi-ide/kapi-lite architecture

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

- Interactive diagram: https://gitdiagram.com/kapi-ide/kapi-lite
- Repository: https://github.com/kapi-ide/kapi-lite

## Overview

##### Project Type and Purpose
- This is an Electron-based desktop application (“Kapi Lite”) with a React/TypeScript renderer and a Node-powered main process.
- Purpose: provide a local-first, AI-powered code review and chat interface that scans the user’s file system, stores context in IndexedDB, and sends selected code snippets to an LLM for analysis.

##### High-Level Architecture
a. User Interface (Renderer Process)
- React components and pages under `src/`
- Bundled by Vite, loaded via `index.html`
b. Preload / IPC Bridge
- `electron/preload.ts` exposes safe APIs via `contextBridge`
c. Main Process (Electron)
- `electron/main.ts` manages windows, routes IPC calls to handlers
- `electron/fileSystemHandlers.ts` enforces permission/security for FS ops
d. Local Services & Storage
- `src/services` : conversationService, fileSystemService, indexedDBService
- Business logic in `src/utils` (chatService, codeCollector, langchainConfig, migrationUtils)
- IndexedDB for persistent context in the browser sandbox
e. External AI Integration
- LLM endpoints (local or remote) accessed via `chatService`/`langchainConfig`

##### Relationships & Data Flows
- Renderer → Preload: UI invokes `window.api.*` methods for FS listing, chat, reviews
- Preload → Main: IPC channel forwards requests (e.g., “select directory”, “read file”)
- Main → File System Handlers: validates paths, reads files, respects `.gitignore`
- Renderer Services → IndexedDB: stores chat history, permissions, migration state
- Renderer Utils → External AI: bundles context, calls LLM, receives and displays suggestions

##### Architectural Patterns & Principles
- **Separation of Concerns**:
- UI (React) vs. platform integration (Electron) vs. business logic (Services/Utils)
- **Security Layer**: permission gating in `fileSystemHandlers.ts`
- **Local-First**: IndexedDB for context persistence, controlled code sharing
- **Modular Code Review Pipeline**: Code collector → prompt generator → LLM call → inline feedback

##### Final Checklist
- Stack vertically: UI → Preload → Main → Services → External LLM
- With filenames or folder names for each component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Renderer Layer
    subgraph "Renderer (React UI)" 
        direction TB
        MainTSX["src/main.tsx"]:::ui
        AppTSX["src/App.tsx"]:::ui
        Components["src/components"]:::ui
        Pages["src/pages"]:::ui
        IndexHTML["index.html"]:::ui
    end

    %% Preload Layer
    Preload["Preload (ipcBridge)\nelectron/preload.ts"]:::electron

    %% Main Process Layer
    MainProc["Main (Electron Process)\nmain.ts\nfileSystemHandlers.ts"]:::electron

    %% Services & Storage Layer
    subgraph "Local Services & Storage"
        direction TB
        FSService["fileSystemService.ts"]:::service
        IndexedDBService["indexedDBService.ts"]:::service
        ConversationService["conversationService.ts"]:::service
        UtilsSub["Business Logic Utils"]:::service
    end

    %% External AI Integration
    LLM["LLM Integration\n(local/remote)"]:::external

    %% Connections
    MainTSX -->|"renders App"| AppTSX
    AppTSX --> UIComps["UI Components"] 
    UIComps -->|"calls api.readDir()"| Preload
    Preload -->|"IPC Calls"| MainProc
    MainProc -->|"responds FS data"| FSService
    AppTSX -->|"uses fileSystemService"| FSService
    AppTSX -->|"uses conversationService"| ConversationService
    ConversationService -->|"stores context"| IndexedDBService
    ConversationService -->|"calls chatService"| UtilsSub
    UtilsSub -->|"requests LLM"| LLM

    %% Click Events
    click MainTSX "https://github.com/kapi-ide/kapi-lite/blob/main/src/main.tsx"
    click AppTSX "https://github.com/kapi-ide/kapi-lite/blob/main/src/App.tsx"
    click Components "https://github.com/kapi-ide/kapi-lite/tree/main/src/components/"
    click Pages "https://github.com/kapi-ide/kapi-lite/tree/main/src/pages/"
    click IndexHTML "https://github.com/kapi-ide/kapi-lite/blob/main/index.html"
    click Preload "https://github.com/kapi-ide/kapi-lite/blob/main/electron/preload.ts"
    click MainProc "https://github.com/kapi-ide/kapi-lite/blob/main/electron/main.ts"
    click FSService "https://github.com/kapi-ide/kapi-lite/blob/main/src/services/fileSystemService.ts"
    click IndexedDBService "https://github.com/kapi-ide/kapi-lite/blob/main/src/services/indexedDBService.ts"
    click ConversationService "https://github.com/kapi-ide/kapi-lite/blob/main/src/services/conversationService.ts"
    click UtilsSub "https://github.com/kapi-ide/kapi-lite/tree/main/src/utils/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef electron fill:#e2e3e5,stroke:#6c757d,color:#383d41;
    classDef service fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
```
