🚀 PagePilot: Your Premium AI RAG Knowledge Assistant

graph TD
    classDef ui fill:#0e1117,stroke:#262730,stroke-width:2px,color:#fff;
    classDef svc fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef rag fill:#0f172a,stroke:#8b5cf6,stroke-width:2px,color:#fff;
    classDef mem fill:#1c1917,stroke:#f59e0b,stroke-width:2px,color:#fff;
    classDef ext fill:#14532d,stroke:#22c55e,stroke-width:2px,color:#fff;

    subgraph UI_Layer [Frontend UI Layer]
        App[app.py]:::ui
        Sidebar[ui/sidebar.py]:::ui
        ChatUI[ui/chat.py]:::ui
        Comp[ui/components.py]:::ui
        CSS[assets/style.css]:::ui
    end

    subgraph Services_Layer [Orchestration Services]
        ChatSvc[services/chat_service.py]:::svc
        IngestSvc[services/ingestion_service.py]:::svc
        UploadSvc[services/upload_service.py]:::svc
    end

    subgraph RAG_Engine [RAG Engine & Vector DB]
        Processor[rag/document_processor.py]:::rag
        Splitter[rag/splitter.py]:::rag
        Embeddings[rag/embeddings.py]:::rag
        Retriever[rag/retriever.py]:::rag
        Prompt[rag/prompt_builder.py]:::rag
        Qdrant[vectorstore/qdrant_manager.py]:::rag
    end

    subgraph Memory_Layer [Session & State Memory]
        Session[memory/session.py]:::mem
        ChatMem[memory/chat_memory.py]:::mem
        Models[models/]:::mem
    end

    subgraph External_APIs [External APIs]
        QdrantCloud[Qdrant Cloud DB]:::ext
        GroqAPI[Groq Inference API]:::ext
        HFModels[HuggingFace Hub]:::ext
    end

    %% UI Connections
    App --> Sidebar
    App --> ChatUI
    Sidebar --> IngestSvc
    Sidebar --> Session
    Sidebar --> Qdrant
    ChatUI --> ChatSvc
    ChatUI --> Comp
    CSS -.-> UI_Layer

    %% Service Connections
    ChatSvc --> Retriever
    ChatSvc --> ChatMem
    ChatSvc --> Prompt
    ChatSvc --> LLM_Factory[llm/factory.py]
    IngestSvc --> Session
    IngestSvc --> Processor
    IngestSvc --> Splitter
    IngestSvc --> Embeddings
    IngestSvc --> Qdrant
    UploadSvc --> Qdrant

    %% RAG Connections
    Retriever --> Qdrant
    Retriever --> Embeddings
    Qdrant --> QdrantCloud
    LLM_Factory --> GroqProvider[llm/groq_provider.py]
    GroqProvider --> GroqAPI
    Embeddings --> HFModels

sequenceDiagram
    autonumber
    actor User
    participant UI as Streamlit UI
    participant ChatService as Chat Service
    participant Retriever as RAG Retriever
    participant DB as Qdrant Cloud
    participant Factory as LLM Factory
    participant LLM as Groq LLM
    
    User->>UI: Enter prompt / Ask question
    UI->>ChatService: query_rag(prompt)
    ChatService->>Retriever: retrieve(prompt)
    Retriever->>DB: Cosine Similarity Search (K=5)
    DB-->>Retriever: Return relevant document chunks
    Retriever-->>ChatService: Return List[Document]
    ChatService->>ChatService: Get Chat History & Build Prompt
    ChatService->>Factory: create()
    Factory-->>ChatService: Return GroqProvider
    ChatService->>LLM: stream(prompt_messages)
    LLM-->>UI: Yield response token chunks (streaming UI)
    UI->>User: Display live streamed response
    ChatService->>ChatService: Rename conversation (if first exchange)

classDiagram
    class BaseLLM {
        <<interface>>
        +stream(messages: List[Dict]) Generator[str]
    }
    class GroqProvider {
        -llm: ChatGroq
        +stream(messages: List[Dict]) Generator[str]
    }
    BaseLLM <|-- GroqProvider : implements

    class LLMFactory {
        +create() BaseLLM$
    }
    LLMFactory ..> BaseLLM : instantiates

    class IngestionService {
        -qdrant_manager: QdrantManager
        +ingest_files(uploaded_files) List[str]
    }

    class UploadService {
        +MAX_FILE_SIZE_MB: int$
        +validate_file(filename, size_bytes) Tuple[bool, str]$
        +run_garbage_collector()$
    }

    class ChatService {
        -llm: BaseLLM
        -retriever: RAGRetriever
        +query_rag(query) Tuple
        +rename_conversation_if_needed(query)
        +generate_title(query) str
    }

    class QdrantManager {
        -client: QdrantClient
        +check_health() bool
        +collection_exists(name) bool
        +create_collection(name, size) bool
        +delete_collection(name) bool
        +get_vector_store(name, embeddings) QdrantVectorStore
    }

    class EmbeddingManager {
        -_instance: HuggingFaceEmbeddings$
        +get_embeddings() HuggingFaceEmbeddings$
    }

    ChatService --> LLMFactory : uses
    ChatService --> RAGRetriever : uses
    IngestionService --> QdrantManager : uses
    IngestionService --> EmbeddingManager : uses