# clovisphere/lucy architecture

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

- Interactive diagram: https://gitdiagram.com/clovisphere/lucy
- Repository: https://github.com/clovisphere/lucy

## Overview

##### Main Components

a) Interface Layer:
- Web Interface (Static files in app/static)
- CLI Interface (cli.py)
- Telegram Bot Integration
- Future WhatsApp Integration (planned)

b) Application Core:
- Main Application Server (app/web.py)
- Request Handlers (app/handlers.py)
- Configuration Management (app/config.py)

c) Helper Services:
- LLM Service (app/helpers/llm.py)
- RAG Implementation (app/helpers/rag.py)
- Logging Service (app/helpers/logger.py)

d) External Services:
- OpenAI API
- Telegram API
- Document Storage
- Vector Database (implied by RAG implementation)

##### Specific Elements

**[User Interfaces]**

- [Web UI] ───┐
- [CLI]    ───┤
- [Telegram]──┤

**[Application Core] <──┘**

- [Request Handlers]
- [Configuration]

- [Helper Services]
- [LLM Service] ────── [OpenAI API]
- [RAG Service] ────── [Vector DB]
- [Logger]

- [Document Storage]

##### Important Notes

- Document indexing flow separately from the query flow
- RAG pipeline specifically as it's a key feature
- A section for future monitoring/telemetry (Prometheus)

##### Technical Details to Emphasize

- FastAPI web server implementation
- Python 3.13 runtime environment
- Environment-based configuration
- Document indexing capability
- Real-time chat functionality

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef interface fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef helper fill:#f1c40f,stroke:#f39c12,color:black
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef config fill:#e74c3c,stroke:#c0392b,color:white
    classDef planned fill:none,stroke:#34495e,stroke-dasharray: 5 5

    %% Interface Layer
    subgraph Interfaces
        WebUI["Web Interface"]:::interface
        CLI["CLI Interface"]:::interface
        Telegram["Telegram Bot"]:::interface
        WhatsApp["WhatsApp Bot (Planned)"]:::planned
    end

    %% Core Layer
    subgraph Core
        AppServer["Application Server"]:::core
        Handlers["Request Handlers"]:::core
        Config["Configuration"]:::config
    end

    %% Helper Services
    subgraph Helpers
        LLM["LLM Service"]:::helper
        RAG["RAG Service"]:::helper
        Logger["Logging Service"]:::helper
    end

    %% External Services
    subgraph External
        OpenAI["OpenAI API"]:::external
        TelegramAPI["Telegram API"]:::external
        VectorDB["Vector Database"]:::external
        DocStorage["Document Storage"]:::external
    end

    %% Relationships
    WebUI --> AppServer
    CLI --> AppServer
    Telegram --> AppServer
    WhatsApp -.-> AppServer
    
    AppServer --> Handlers
    AppServer --> Config
    
    Handlers --> LLM
    Handlers --> RAG
    Handlers --> Logger
    
    LLM --> OpenAI
    RAG --> VectorDB
    RAG --> DocStorage
    Telegram --> TelegramAPI

    %% Click Events
    click WebUI "https://github.com/clovisphere/lucy/tree/main/app/static/"
    click CLI "https://github.com/clovisphere/lucy/blob/main/cli.py"
    click AppServer "https://github.com/clovisphere/lucy/blob/main/app/web.py"
    click Handlers "https://github.com/clovisphere/lucy/blob/main/app/handlers.py"
    click Config "https://github.com/clovisphere/lucy/blob/main/app/config.py"
    click LLM "https://github.com/clovisphere/lucy/blob/main/app/helpers/llm.py"
    click RAG "https://github.com/clovisphere/lucy/blob/main/app/helpers/rag.py"
    click Logger "https://github.com/clovisphere/lucy/blob/main/app/helpers/logger.py"

    %% Legend
    subgraph Legend
        L1["Interface Component"]:::interface
        L2["Core Component"]:::core
        L3["Helper Service"]:::helper
        L4["External Service"]:::external
        L5["Configuration"]:::config
        L6["Planned Feature"]:::planned
    end
```
