# dhananjaylab/oracle-mcp architecture

> Architecture diagram of the GitHub repository dhananjaylab/oracle-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhananjaylab/oracle-mcp
- Repository: https://github.com/dhananjaylab/oracle-mcp

## Overview

##### Project type and purpose
- From the file list and README, this is a Python-based backend/data-processing pipeline with a small REST service layer.
- Its purpose is to:
- Provision and seed a relational database (SQL scripts + `setup_database.py`)
- Ingest and vectorize product/invoice data (`process_vector_products.py`, various `*.sql` inserts)
- Offer search and invoice-item services via lightweight Python servers (`product_search.py`, `server_invoice_items.py`, `main.py` orchestrator)

##### File structure
─ Top-level Python modules:
- `setup_database.py` – creates schema (reads `script.sql`)
- `oracle_conn.py` – database connection wrapper
- `process_vector_products.py` – transforms product data into vector embeddings
- `product_search.py` – implements similarity search queries
- `server_invoice_items.py` – serves invoice-item lookups
- `main.py` – possible entry-point/orchestrator to launch services or batch processes
- `setup.ipynb` – exploratory notebook for initial setup/demo
─ SQL artifacts:
- Schema and seed scripts (`script.sql`, `inserts_products_books.sql`, `invoice_data_insert.sql`, `similarity_search.sql`)
─ Config/dependencies: `requirements.txt`

##### README

a. Main components
1. Database layer (Oracle or RDBMS)
2. Data Ingestion & Provisioning module
3. Vectorization & Indexing module
4. Search & Invoice-Item API services
5. Optional: Orchestration layer (`main.py`)
6. Development notebook (`setup.ipynb`)
7. External libraries/services (e.g., vector embedding library, Oracle client)

b. Relationships & interactions
- Data Ingestion → Database (via `oracle_conn.py`)
- Vectorization module reads from DB, produces embeddings, writes back or to a vector index table
- Search API queries the vector index table (and invoice tables) to serve client requests
- Orchestrator may trigger ingestion, vectorization, and launch servers
- The notebook is a side-channel for manual setup or experimentation

c. Architectural patterns & design principles
- Separation of concerns: ingestion vs. processing vs. serving
- Single responsibility per Python module
- SQL scripts handle DDL/DML, Python code handles orchestration and logic
- Potential batch + microservice hybrid (batch vector processing + lightweight REST)

d. Key technologies/frameworks
- Python 3.x
- Oracle (or another RDBMS) via `cx_Oracle` or similar
- Vector embedding library (e.g., SentenceTransformers, if used in `process_vector_products.py`)
- Flask/FastAPI (or built-in HTTP server) in `product_search.py` & `server_invoice_items.py`
- Jupyter for exploratory tasks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External / Database
    DB["Oracle DB<br/>(Products, Invoices, VectorIndex)"]:::external

    %% Batch Layer
    subgraph "Batch Layer"
        direction TB
        SetupDB["setup_database.py"]:::batch
        OracleConn["oracle_conn.py"]:::batch
        ProcessVec["process_vector_products.py"]:::batch
        SimSearchSQL["similarity_search.sql"]:::batch
    end

    %% Real-time Services
    subgraph "Real-time Services"
        direction TB
        SearchAPI["product_search.py"]:::realtime
        InvoiceAPI["server_invoice_items.py"]:::realtime
    end

    %% Orchestration
    main["main.py"]:::orchestration

    %% Notebook
    Notebook["setup.ipynb"]:::notebook

    %% Config & Dependencies
    Req["requirements.txt"]:::external
    Readme["README.md"]:::external

    %% Batch Flows
    SetupDB -->|"runs SQL scripts\n(script.sql,\ninserts_products_books.sql,\ninvoice_data_insert.sql)"| DB
    OracleConn -->|connects to| DB
    ProcessVec -->|"reads data\n& writes embeddings"| DB
    ProcessVec -->|uses| SimSearchSQL

    %% Service Flows
    SearchAPI -->|"SQL vector search\n(similarity_search.sql)"| DB
    InvoiceAPI -->|"SQL invoice lookup"| DB

    %% Orchestration Flows
    main -->|orchestrates| SetupDB
    main -->|orchestrates| ProcessVec
    main -->|launches| SearchAPI
    main -->|launches| InvoiceAPI

    %% Notebook Flow
    Notebook -.->|manual setup / demo| DB

    %% Config Dependencies
    Req -.->|dependencies for| SetupDB
    Req -.->|dependencies for| ProcessVec
    Req -.->|dependencies for| SearchAPI
    Req -.->|dependencies for| InvoiceAPI
    Readme -.->|docs for| Req

    %% Click Events
    click SetupDB "https://github.com/dhananjaylab/oracle-mcp/blob/main/setup_database.py"
    click OracleConn "https://github.com/dhananjaylab/oracle-mcp/blob/main/oracle_conn.py"
    click ProcessVec "https://github.com/dhananjaylab/oracle-mcp/blob/main/process_vector_products.py"
    click SimSearchSQL "https://github.com/dhananjaylab/oracle-mcp/blob/main/similarity_search.sql"
    click SearchAPI "https://github.com/dhananjaylab/oracle-mcp/blob/main/product_search.py"
    click InvoiceAPI "https://github.com/dhananjaylab/oracle-mcp/blob/main/server_invoice_items.py"
    click main "https://github.com/dhananjaylab/oracle-mcp/blob/main/main.py"
    click Notebook "https://github.com/dhananjaylab/oracle-mcp/blob/main/setup.ipynb"
    click Req "https://github.com/dhananjaylab/oracle-mcp/blob/main/requirements.txt"
    click Readme "https://github.com/dhananjaylab/oracle-mcp/blob/main/README.md"

    %% Styles
    classDef batch fill:#ADD8E6,stroke:#000;
    classDef realtime fill:#90EE90,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
    classDef orchestration fill:#FFA500,stroke:#000;
    classDef notebook fill:#FFFFFF,stroke-dasharray: 5 5,stroke:#000;
```
