# liweiphys/layra architecture

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

- Interactive diagram: https://gitdiagram.com/liweiphys/layra
- Repository: https://github.com/liweiphys/layra

## Overview

##### Project Type and Purpose
- Layra is a full-stack, retrieval-augmented generation (RAG) platform with a Next.js/TailwindCSS frontend and a FastAPI-based asynchronous backend.
- It ingests PDF documents as images, generates visual embeddings, stores metadata and vectors, and exposes a chat-style QA interface that preserves layout.

##### File-Structure Insights
- Top-level directories:
- app/       ← FastAPI backend, organized into api, core, db, models, schemas, rag, utils, framework
- web/       ← Next.js 15 + TypeScript frontend
- docker/    ← Docker-Compose definitions for Milvus, Redis, MongoDB, Kafka, MinIO
- model_server.py ← standalone ColBERT embedding service
- Key config files: .env, alembic.ini, docker-compose.yml, gunicorn_config.py, next.config.ts
- Asynchronous/event-driven: Kafka consumers/producers, SSE endpoints, background embedding jobs.

##### README Architecture Sections
- Query flow: embedding → vector retrieval → answer generation
- Upload flow: PDF → image pages → ColQwen2.5 embeddings → Milvus + metadata stores
- Tech stack: FastAPI, Kafka, Redis, MySQL, MongoDB, MinIO, Milvus, Next.js

##### Main Components and Interactions
a. Frontend (Next.js)
- Renders UI pages (chat, knowledge base, sign-in)
- Calls REST/API (chatApi, configApi, kbApi)
- Maintains auth/chat/config state via Zustand
b. Backend (FastAPI)
- HTTP endpoints (app/api/endpoints/*.py) for auth, chat, SSE, config
- Core modules for config, logging, security
- Schemas/models define request/response and DB ORM
- RAG services (app/rag) invoke embedding service and LLM
- Framework layer (app/framework/app_framework.py) sets up middleware, routers
c. Embedding Service (model_server.py)
- Hosts ColQwen2.5 visual embedding model
- Receives page images, returns dense vectors
d. Data Stores
- Milvus: vector similarity search
- MySQL (via SQLAlchemy/Alembic): relational metadata (users, configs)
- MongoDB: document metadata, conversation history
- MinIO: raw PDF files and page images
- Redis: caching, session/state management
e. Message Broker / Background Jobs
- Kafka:
- Producer: when PDF is uploaded, produce “new-document” event
- Consumer: long-running job to parse PDF → images → embedding → store
f. External LLMs
- Qwen2.5-VL (and future GPT-4o, Claude) invoked via llm_service
g. Clients/Users
- Browser users interact via web UI over HTTPS
- Optionally any OpenAI-compatible client via API

##### Architectural Patterns and Principles
- Async-first, event-driven pipeline (FastAPI + Kafka)
- Microservice-style separation: embedding service vs. core API
- RAG pattern: separation of retrieval (Milvus) and generation (LLM)
- Clean layering: API → services → data access → external integrations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Legend
    subgraph Legend
        direction LR
        Svc[Service]:::service
        DB[Database]:::database
        MQ[Message Queue]:::queue
    end

    classDef service fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef database fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef queue fill:#FFE5CC,stroke:#FF8C00,color:#FF8C00;
    classDef user fill:#F0E6FF,stroke:#800080,color:#800080;

    %% Upload & Indexing Flow
    subgraph "Upload & Indexing Flow"
        direction TB
        User1["User"]:::user
        FE_Upload["Next.js App (Upload)"]:::service
        BE_Upload["Upload API<br>app/api/endpoints/base.py"]:::service
        KafkaProd["Kafka Producer<br>app/utils/kafka_producer.py"]:::queue
        KafkaTopic["document.events"]:::queue
        KafkaCons["Kafka Consumer<br>app/utils/kafka_consumer.py"]:::service
        FileStore["MinIO<br>app/db/miniodb.py"]:::database
        Converter["File Conversion<br>app/rag/convert_file.py"]:::service
        EmbService["Embedding Service<br>model_server.py"]:::service
        MilvusStore["Milvus<br>app/db/milvus.py"]:::database
        MySQLMeta["MySQL<br>app/db/mysql_base.py"]:::database
        MongoMeta["MongoDB<br>app/db/mongo.py"]:::database

        User1 -->|uploads PDF| FE_Upload
        FE_Upload -->|POST /api/upload| BE_Upload
        BE_Upload -->|produce new-document| KafkaProd
        KafkaProd -->|to document.events| KafkaTopic
        KafkaTopic --> KafkaCons
        KafkaCons --> Converter
        Converter --> FileStore
        Converter --> EmbService
        EmbService --> MilvusStore
        Converter --> MySQLMeta
        Converter --> MongoMeta
    end

    %% Query Flow
    subgraph "Query Flow"
        direction TB
        User2["User"]:::user
        FE_Chat["Chat Page"]:::service
        BE_Chat["Chat API<br>app/api/endpoints/chat.py"]:::service
        MilvusSearch["Milvus Search<br>app/db/milvus.py"]:::database
        LLM["LLM Service<br>app/rag/llm_service.py"]:::service
        SSE["SSE Endpoint<br>app/api/endpoints/sse.py"]:::service
        RedisCache["Redis<br>app/db/redis.py"]:::database
        MongoConv["MongoDB<br>app/db/mongo.py"]:::database

        User2 -->|asks question| FE_Chat
        FE_Chat -->|POST /api/chat| BE_Chat
        BE_Chat -->|vector_search| MilvusSearch
        BE_Chat -->|get convo| MongoConv
        BE_Chat -->|cache context| RedisCache
        BE_Chat -->|call llm| LLM
        LLM -->|answer| BE_Chat
        BE_Chat -->|SSE stream| SSE
        SSE --> FE_Chat
    end

    %% Click Events
    click FE_Chat "https://github.com/liweiphys/layra/blob/main/web/src/app/ai-chat/page.tsx"
    click FE_Upload "https://github.com/liweiphys/layra/blob/main/web/src/app/knowledge-base/page.tsx"
    click FE_Upload "https://github.com/liweiphys/layra/blob/main/web/src/app/sign-in/page.tsx"
    click FE_Chat "https://github.com/liweiphys/layra/blob/main/web/src/lib/api/chatApi.ts"
    click BE_Chat "https://github.com/liweiphys/layra/blob/main/app/api/endpoints/chat.py"
    click SSE "https://github.com/liweiphys/layra/blob/main/app/api/endpoints/sse.py"
    click KafkaProd "https://github.com/liweiphys/layra/blob/main/app/utils/kafka_producer.py"
    click KafkaCons "https://github.com/liweiphys/layra/blob/main/app/utils/kafka_consumer.py"
    click Converter "https://github.com/liweiphys/layra/blob/main/app/rag/convert_file.py"
    click EmbService "https://github.com/liweiphys/layra/blob/main/model_server.py"
    click MilvusStore "https://github.com/liweiphys/layra/blob/main/app/db/milvus.py"
    click MySQLMeta "https://github.com/liweiphys/layra/blob/main/app/db/mysql_base.py"
    click MongoMeta "https://github.com/liweiphys/layra/blob/main/app/db/mongo.py"
    click RedisCache "https://github.com/liweiphys/layra/blob/main/app/db/redis.py"
```
