# milvus-io/milvus-lite architecture

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

- Interactive diagram: https://gitdiagram.com/milvus-io/milvus-lite
- Repository: https://github.com/milvus-io/milvus-lite

## Overview

##### Project type and purpose
- Milvus Lite is a language-library/CLI tool that embeds a high-performance vector DB engine in Python applications (e.g. Jupyter notebooks, edge devices).
- It provides the same API as Milvus Standalone/Distributed but runs locally via a C++ gRPC server + Python client wrapper.

##### Main components
a. Python Layer
- MilvusClient API (pymilvus)
- milvus_lite.cmdline (CLI entrypoint for dump & management)
- milvus_lite.server & server_manager (spawns/manages the local C++ server process)
b. IPC/Network
- gRPC (proto files under src/proto define service & messages)
c. C++ Layer (local server process)
- gRPC Server (server.cpp)
- Service Implementation (milvus_service_impl.cpp)
- Proxy Layer (milvus_proxy.cpp) – dispatches calls to local vs remote
- Core Engine (milvus_local.cpp) – implements collection, insert, delete, search, query
- Task Modules (e.g. create_collection_task, insert_task, search_task, hybrid_search_task)
- Parser Module (ANTLR4 grammar + generated PlanParser, visitor)
- Storage Layer (storage/*.cpp) – metadata & vector persistence in local file(s)
- Index Layer (segcore_wrapper + thirdparty knowhere library)
- Utilities (schema_util, string_util, timer, status)
d. External Tools & Build
- CMake + Conan (build system & dependency management)
- Dockerfiles (under scripts) for packaging manylinux wheels or containers

##### Relationships & data flows
1. Python app calls MilvusClient methods →
2. server_manager.launch() spins up the local C++ server (subprocess) →
3. Python MilvusClient opens gRPC channel to localhost:19530 →
4. gRPC call → ServiceImpl → Proxy → Core Engine (milvus_local) →
a. Core Engine calls Task modules
b. Task modules coordinate Parser (for DSL/Plan), Storage, Index
c. Storage persists data, Index layer builds/queries vector indexes
5. Results bubble back up through gRPC → Python client → user code

##### Architectural patterns & design principles
- Client-Server pattern (Python gRPC client ↔ C++ gRPC server)
- Layered architecture:
- Presentation layer (Python API & CLI)
- Service layer (gRPC service impl, proxy)
- Domain layer (tasks, parser)
- Persistence layer (storage) & algorithmic layer (vector index)
- Plugin/extensibility points:
- Parser grammar (ANTLR) for adding new DSL commands
- Index abstraction (segcore_wrapper → knowhere backends)
- Storage abstraction

##### Final checklist
- Clearly label: Python Client, Server Manager, C++ Server (with sub-components), Storage, Index.
- Startup flow (Python → spawn C++ server)
- RPC calls (MilvusClient → gRPC → ServiceImpl → Proxy → Core Engine → …)
- Data flow (insert/search/query → storage/index → response)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python Side
    subgraph "Python Side"
        direction TB
        A["MilvusClient API"]:::python
        B["CLI Entry: milvus-lite"]:::python
        C["Server Wrapper"]:::python
        D["Server Manager"]:::python
    end

    %% C++ Side
    subgraph "C++ Side"
        direction TB
        S1["gRPC & Protobuf"]:::cpp
        S2["gRPC Server"]:::cpp
        S3["Service Implementation"]:::cpp
        S4["Proxy Layer"]:::cpp
        S5["Core Engine"]:::cpp

        subgraph "Task Modules"
            direction TB
            T1["CreateCollectionTask"]:::cpp
            T2["CreateIndexTask"]:::cpp
            T3["InsertTask"]:::cpp
            T4["DeleteTask"]:::cpp
            T5["QueryTask"]:::cpp
            T6["SearchTask"]:::cpp
            T7["HybridSearchTask"]:::cpp
            T8["UpsertTask"]:::cpp
        end

        subgraph "Parser Module"
            direction TB
            P1["ANTLR Grammar"]:::parser
            P2["Generated ANTLR Code"]:::parser
            P3["Parser Entry"]:::parser
            P4["Parser Utilities"]:::parser
        end

        subgraph "Storage Layer"
            direction TB
            ST1["Storage Files"]:::storage
            ST2["Collection Meta"]:::storage
            ST3["Collection Data"]:::storage
            ST4["BM25 Stats"]:::storage
        end

        subgraph "Index Layer"
            direction TB
            I1["segcore_wrapper"]:::index
            I2["Knowhere Backends"]:::index
        end

        subgraph "Utilities"
            direction TB
            U1["Schema Util"]:::util
            U2["String Util"]:::util
            U3["Timer"]:::util
            U4["Status Codes"]:::util
        end
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        BM1["CMake Scripts"]:::build
        BM2["Conan File"]:::build
        BM3["Docker Packaging"]:::build
        BM4["Build Helpers"]:::build
    end

    %% Flows
    A -->|"calls launch()"| D
    D -->|"spawns"| S2
    A -->|"opens gRPC"| S1
    S1 -->|"serves RPC to"| S2
    S2 -->|"invokes"| S3
    S3 -->|"forwards to"| S4
    S4 -->|"dispatches to"| S5
    S5 -->|"executes task"| T1
    S5 -->|"executes task"| T2
    S5 -->|"executes task"| T3
    S5 -->|"executes task"| T4
    S5 -->|"executes task"| T5
    S5 -->|"executes task"| T6
    S5 -->|"executes task"| T7
    S5 -->|"executes task"| T8
    T1 -->|"uses grammar"| P1
    P1 --> P2 --> P3 --> P4
    T1 -->|"persists via"| ST1
    ST1 --> ST2
    ST1 --> ST3
    ST1 --> ST4
    T6 -->|"queries index"| I1
    I1 --> I2
    S5 -->|"utilizes"| U1
    S5 -->|"utilizes"| U2
    S5 -->|"utilizes"| U3
    S5 -->|"utilizes"| U4
    BM1 --> BM2
    BM1 --> BM3
    BM1 --> BM4

    %% Return flow
    S5 -->|"returns result"| S4 -->|"returns"| S3 -->|"returns"| S2 -->|"returns via gRPC"| A

    %% Click Events
    click A "https://github.com/milvus-io/milvus-lite/blob/main/python/src/milvus_lite/__init__.py"
    click B "https://github.com/milvus-io/milvus-lite/blob/main/python/src/milvus_lite/cmdline.py"
    click C "https://github.com/milvus-io/milvus-lite/blob/main/python/src/milvus_lite/server.py"
    click D "https://github.com/milvus-io/milvus-lite/blob/main/python/src/milvus_lite/server_manager.py"
    click S1 "https://github.com/milvus-io/milvus-lite/blob/main/src/proto/milvus.proto"
    click S2 "https://github.com/milvus-io/milvus-lite/blob/main/src/server.cpp"
    click S3 "https://github.com/milvus-io/milvus-lite/blob/main/src/milvus_service_impl.cpp"
    click S4 "https://github.com/milvus-io/milvus-lite/blob/main/src/milvus_proxy.cpp"
    click S5 "https://github.com/milvus-io/milvus-lite/blob/main/src/milvus_local.cpp"
    click T1 "https://github.com/milvus-io/milvus-lite/blob/main/src/create_collection_task.cpp"
    click T2 "https://github.com/milvus-io/milvus-lite/blob/main/src/create_index_task.cpp"
    click T3 "https://github.com/milvus-io/milvus-lite/blob/main/src/insert_task.cpp"
    click T4 "https://github.com/milvus-io/milvus-lite/blob/main/src/delete_task.cpp"
    click T5 "https://github.com/milvus-io/milvus-lite/blob/main/src/query_task.cpp"
    click T6 "https://github.com/milvus-io/milvus-lite/blob/main/src/search_task.cpp"
    click T7 "https://github.com/milvus-io/milvus-lite/blob/main/src/hybrid_search_task.cpp"
    click T8 "https://github.com/milvus-io/milvus-lite/blob/main/src/upsert_task.cpp"
    click P1 "https://github.com/milvus-io/milvus-lite/blob/main/src/parser/Plan.g4"
    click P3 "https://github.com/milvus-io/milvus-lite/blob/main/src/parser/parser.cc"
    click ST1 "https://github.com/milvus-io/milvus-lite/blob/main/src/storage/storage.cpp"
    click ST2 "https://github.com/milvus-io/milvus-lite/blob/main/src/storage/collection_meta.cpp"
    click ST3 "https://github.com/milvus-io/milvus-lite/blob/main/src/storage/collection_data.cpp"
    click ST4 "https://github.com/milvus-io/milvus-lite/blob/main/src/storage/bm25_stats.cpp"
    click I1 "https://github.com/milvus-io/milvus-lite/blob/main/src/segcore_wrapper.cpp"
    click U1 "https://github.com/milvus-io/milvus-lite/blob/main/src/schema_util.cpp"
    click U2 "https://github.com/milvus-io/milvus-lite/blob/main/src/string_util.hpp"
    click U3 "https://github.com/milvus-io/milvus-lite/blob/main/src/timer.cpp"
    click U4 "https://github.com/milvus-io/milvus-lite/blob/main/src/status.h"
    click BM1 "https://github.com/milvus-io/milvus-lite/blob/main/CMakeLists.txt"
    click BM2 "https://github.com/milvus-io/milvus-lite/blob/main/conanfile.py"
    click BM3 "https://github.com/milvus-io/milvus-lite/blob/main/scripts/Dockerfile.manylinux.x86_64"
    click BM4 "https://github.com/milvus-io/milvus-lite/blob/main/scripts/build.sh"

    %% Styles
    classDef python fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef cpp fill:#E0FFFF,stroke:#333,stroke-width:1px
    classDef storage fill:#FFDAB9,stroke:#333,stroke-width:1px
    classDef index fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef parser fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef util fill:#F0FFF0,stroke:#333,stroke-width:1px
    classDef build fill:#D3D3D3,stroke:#333,stroke-width:1px
```
