# whyhow-ai/knowledge-table architecture

> Architecture diagram of the GitHub repository whyhow-ai/knowledge-table, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whyhow-ai/knowledge-table
- Repository: https://github.com/whyhow-ai/knowledge-table

## Overview

##### Main Components
- Frontend: The UI built with TypeScript/React (using Vite and Bun) that users interact with. It includes components for displaying tables, handling document uploads, and interacting with various interface elements (like file drop areas, table controls, and menu buttons).
- Backend: A Python-based API (using FastAPI/uvicorn) that exposes endpoints for document extraction, query processing, and graph operations. Its structure is organized into clearly defined submodules (API endpoints, models, services, schemas, and core configuration).
- Services: A collection of services within the backend responsible for:
- Document Extraction (document endpoints and services)
- Graph and Query processing (graph endpoints and query endpoints)
- Integrations with external providers such as OpenAI for language and embedding services, as well as potential integration with the Unstructured API.
- Vector Database integrations: The backend supports multiple vector databases (Milvus, Qdrant, etc.) via specific service factories.
- External Integrations: External AI providers (OpenAI initially) for extracting and embedding, as well as optional integrations like the Unstructured API. Additionally, integration with vector databases (Milvus, Qdrant) plays a key role.
- Data Stores: Although not a classical database layer from relational perspectives, the project integrates with vector databases and is planning support for traditional databases like PostgreSQL or MongoDB in the roadmap.

##### Architectural Patterns & Key Principles
- Separation of Concerns: Clearly separate frontend presentation, API endpoint handling, business logic/services, and external integrations.
- Modularity and Extensibility: Use factories for embedding, LLM, loaders, and vector DB services, indicating design patterns that support plug-and-play components.
- API-Centric Design: The backend is a REST API server (using FastAPI/uvicorn) organized with versioning (v1) and clearly defined endpoint modules.
- Containerization & Environment Configuration: Multiple Dockerfiles and docker-compose configurations suggest an architecture optimized for containerized deployment.

##### Final Recommendations to the Principal Software Engineer
- How the system facilitates RAG pipelines by converting unstructured documents into structured data tables and graphs, and highlight the integration flexibility (e.g., support for multiple vector DBs, future integrations with additional LLM providers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    U("User/Client"):::client

    subgraph "Frontend"
        FE("Frontend UI (React/Vite/Bun)"):::frontend
        TD("Table Display"):::frontendComponent
        FD("Document Upload (File Drop Zone)"):::frontendComponent
        MB("Menu Buttons"):::frontendComponent
    end

    U --> FE
    FE --> TD
    FE --> FD
    FE --> MB
    FE -->|"HTTP/REST"| BA

    subgraph "Backend"
        subgraph "API Endpoints"
            BA("Backend API Server (FastAPI)"):::backend
            DE("Document Endpoint"):::backendEndpoint
            GE("Graph Endpoint"):::backendEndpoint
            QE("Query Endpoint"):::backendEndpoint
        end
        BA --> DE
        BA --> GE
        BA --> QE

        subgraph "Services"
            DS("Document Extraction Service"):::backendService
            EF("Embedding Service Factory"):::backendService
            OE("OpenAI Embedding Service"):::backendService
            LF("LLM Service Factory"):::backendService
            OL("OpenAI LLM Service"):::backendService
            LF2("Loaders Service Factory"):::backendService
            PP("PyPDF Service"):::backendService
            US("Unstructured Service"):::backendService
            GS("Graph Processing Service"):::backendService
            QS("Query Service"):::backendService
            VDF("Vector DB Factory"):::backendService
            MV("Milvus Service"):::backendService
            QD("Qdrant Service"):::backendService
        end

        subgraph "Core & Models"
            CC("Core Configuration & Dependencies"):::core
            DM("Data Models"):::core
            SC("Schema/Validation"):::core
        end

        %% Illustrative connections from endpoints to services
        DE --> DS
        GE --> GS
        QE --> QS

        %% Internal service dependencies
        EF --> OE
        LF --> OL
        LF2 --> PP
        LF2 --> US
        VDF --> MV
        VDF --> QD
    end

    %% Connections from Frontend to Backend
    FE -->|"API Request"| BA

    %% External Integrations
    subgraph "External Integrations"
        OA("OpenAI (External AI Provider)"):::external
        MDB("Milvus (Vector DB)"):::externalDB
        QDB("Qdrant (Vector DB)"):::externalDB
    end

    %% Service connections to external integrations
    OE --> OA
    OL --> OA
    MV --> MDB
    QD --> QDB

    %% Deployment & Containerization
    subgraph "Deployment"
        BD("Backend Dockerfile"):::deployment
        FDocker("Frontend Dockerfile"):::deployment
        DC("Docker Compose (Backend)"):::deployment
        DCP("Docker Compose (Project)"):::deployment
    end

    %% Additional illustrative connections from endpoints to services
    BA -->|"triggers"| DS
    EF -.->|"uses"| OE
    LF -.->|"uses"| OL
    LF2 -.->|"uses"| PP
    LF2 -.->|"uses"| US
    VDF -.->|"selects"| MV
    VDF -.->|"selects"| QD

    classDef client fill:#fef3bd,stroke:#333,stroke-width:2px;
    classDef frontend fill:#a3d5ff,stroke:#333,stroke-width:2px;
    classDef frontendComponent fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef backend fill:#ffdbcc,stroke:#333,stroke-width:2px;
    classDef backendEndpoint fill:#ffc2b3,stroke:#333,stroke-width:1px;
    classDef backendService fill:#ffeedb,stroke:#333,stroke-width:1px;
    classDef core fill:#d0e9c6,stroke:#333,stroke-width:1px;
    classDef external fill:#d6eaf8,stroke:#333,stroke-width:2px;
    classDef externalDB fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef deployment fill:#f5c6cb,stroke:#333,stroke-width:1px;

    click FE "https://github.com/whyhow-ai/knowledge-table/tree/main/frontend/"
    click TD "https://github.com/whyhow-ai/knowledge-table/tree/main/frontend/src/components/kt/kt-table"
    click FD "https://github.com/whyhow-ai/knowledge-table/blob/main/frontend/src/components/kt/kt-file-drop.tsx"
    click MB "https://github.com/whyhow-ai/knowledge-table/tree/main/frontend/src/components/menu-button"
    click BA "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/main.py"
    click DE "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/api/v1/endpoints/document.py"
    click GE "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/api/v1/endpoints/graph.py"
    click QE "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/api/v1/endpoints/query.py"
    click CC "https://github.com/whyhow-ai/knowledge-table/tree/main/backend/src/app/core"
    click DM "https://github.com/whyhow-ai/knowledge-table/tree/main/backend/src/app/models"
    click SC "https://github.com/whyhow-ai/knowledge-table/tree/main/backend/src/app/schemas"
    click DS "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/document_service.py"
    click EF "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/embedding/factory.py"
    click OE "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/embedding/openai_embedding_service.py"
    click LF "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/llm/factory.py"
    click OL "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/llm/openai_llm_service.py"
    click LF2 "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/loaders/factory.py"
    click PP "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/loaders/pypdf_service.py"
    click US "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/loaders/unstructured_service.py"
    click GS "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/graph_service.py"
    click QS "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/query_service.py"
    click VDF "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/vector_db/factory.py"
    click MV "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/vector_db/milvus_service.py"
    click QD "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/src/app/services/vector_db/qdrant_service.py"
    click BD "https://github.com/whyhow-ai/knowledge-table/tree/main/backend/src/Dockerfile"
    click FDocker "https://github.com/whyhow-ai/knowledge-table/tree/main/frontend/Dockerfile"
    click DC "https://github.com/whyhow-ai/knowledge-table/blob/main/backend/docker-compose.yml"
    click DCP "https://github.com/whyhow-ai/knowledge-table/blob/main/docker-compose.yml"
```
