# shyamsridhar123/graphai architecture

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

- Interactive diagram: https://gitdiagram.com/shyamsridhar123/graphai
- Repository: https://github.com/shyamsridhar123/graphai

## Overview

##### Project type and purpose
- This is an open‐source, educational “intelligent knowledge graph” platform built in Python that uses Azure Cosmos DB (Gremlin API) for graph storage and Azure OpenAI for NLP/embedding services.
- Its purpose is to ingest natural‐language business events, extract entities/relationships over time (episodic ingestion), store them in a graph, then provide semantic search, analytics, and auto‐generated intelligence reports via CLI/demos (and future REST API).

##### File structure
- Top‐level directories:
- src/ – core GraphitiCosmos implementation (GraphitiCosmos class + asynchronous methods).
- demos/ – interactive and scenario demos (CLI‐style interfaces for exploratory use).
- scripts/ – data import, test‐data generation, environment setup helpers.
- data/ – sample and combined Manybirds e-commerce product/event datasets.
- docs/ – design docs, use‐case writeups, data‐loading guidance.
- visualizations/ – markdown with graph visualizations.
- intelligence_reports/ & ecommerce_intelligence_reports/ – generated BI outputs.
- Project config: pyproject.toml, uv.lock, .env, .gitignore.
- There's a single test file (test_search_enhanced.py) at root verifying search semantics.

##### README for additional insights
- The README details a layered, event‐driven architecture: Presentation, Business Logic, and Data layers.
- It lists key technologies: Azure Cosmos DB Gremlin API, Azure OpenAI (GPT-4 & embeddings), Python 3.12+, Gremlin Python driver, FastAPI (future REST API).

##### Diagramming conventions
- Related files under each component in small callouts (e.g., list demos/*.py under Presentation Layer).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        style PresentationLayer fill:#cce5ff,stroke:#333,stroke-width:2px
        CLI("CLI & Demo Apps"):::frontend
        RESTAPI("Future REST API (FastAPI)"):::frontend
        Reports("Generated Reports"):::frontend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        style BusinessLayer fill:#d4edda,stroke:#333,stroke-width:2px
        EpisodeEngine("Episode Processing Engine"):::business
        SearchEngine("Search Engine"):::business
        AnalyticsEngine("Analytics Engine"):::business
        BIGenerator("Business Intelligence Generator"):::business
    end

    %% Data Layer
    subgraph "Data Layer"
        style DataLayer fill:#ffe5b4,stroke:#333,stroke-width:2px
        CosmosDB["Azure Cosmos DB\n(Gremlin API)"]:::db
        OpenAI["Azure OpenAI Services\n(GPT-4 & Embeddings)"]:::cloud
        Config("Configuration & State\n(.env, pyproject.toml,\nKey Retrieval Scripts)"):::config
    end

    %% Support & Tools
    subgraph "Support & Tools"
        style SupportTools fill:#f8f9fa,stroke:#333,stroke-width:2px
        Ingestion("Data Ingestion Scripts"):::scripts
        Datasets("Sample Datasets"):::data
        Documentation("Documentation & Use Cases"):::docs
        Visualization("Visualization Examples"):::vis
        Testing("Testing\n(test_search_enhanced.py)"):::test
    end

    %% Connections
    CLI -->|uses| EpisodeEngine
    RESTAPI -->|calls| EpisodeEngine
    EpisodeEngine -->|"writes events"| CosmosDB
    EpisodeEngine -->|"analyzes text"| OpenAI
    SearchEngine -->|queries| CosmosDB
    AnalyticsEngine -->|traverses graph| CosmosDB
    AnalyticsEngine -->|uses embeddings| OpenAI
    BIGenerator -->|consumes results| SearchEngine
    BIGenerator -->|consumes analytics| AnalyticsEngine
    BIGenerator -->|outputs reports| Reports

    %% Support flows
    Ingestion -->|loads data into| CosmosDB
    Datasets -->|feeds| Ingestion
    Documentation -.->|guides| CLI
    Documentation -.->|guides| Ingestion
    Visualization -.->|example outputs| Reports
    Testing -.->|validates| SearchEngine

    %% Click Events - Presentation
    click CLI "https://github.com/shyamsridhar123/graphai/blob/main/demos/interactive_demo.py"
    click CLI "https://github.com/shyamsridhar123/graphai/blob/main/demos/demo_graphiti_cosmos.py"
    click CLI "https://github.com/shyamsridhar123/graphai/blob/main/demos/ecommerce_intelligence_demo_fixed.py"
    click CLI "https://github.com/shyamsridhar123/graphai/blob/main/demos/compelling_use_case_demo_fixed.py"
    click CLI "https://github.com/shyamsridhar123/graphai/blob/main/demos/visualization_demo.py"
    click Reports "https://github.com/shyamsridhar123/graphai/tree/main/intelligence_reports/"
    click Reports "https://github.com/shyamsridhar123/graphai/tree/main/ecommerce_intelligence_reports/"

    %% Click Events - Business
    click EpisodeEngine "https://github.com/shyamsridhar123/graphai/blob/main/src/graphiti_cosmos.py"
    click SearchEngine "https://github.com/shyamsridhar123/graphai/blob/main/src/graphiti_cosmos.py"
    click AnalyticsEngine "https://github.com/shyamsridhar123/graphai/blob/main/src/graphiti_cosmos.py"
    click BIGenerator "https://github.com/shyamsridhar123/graphai/blob/main/src/graphiti_cosmos.py"

    %% Click Events - Data
    click CosmosDB "https://github.com/shyamsridhar123/graphai/blob/main/src/graphiti_cosmos.py"
    click OpenAI "https://github.com/shyamsridhar123/graphai/blob/main/src/graphiti_cosmos.py"
    click Config "https://github.com/shyamsridhar123/graphai/blob/main/.env"
    click Config "https://github.com/shyamsridhar123/graphai/blob/main/pyproject.toml"
    click Config "https://github.com/shyamsridhar123/graphai/blob/main/scripts/get_cosmos_keys.ps1"
    click Config "https://github.com/shyamsridhar123/graphai/blob/main/scripts/setup_environment.ps1"

    %% Click Events - Support & Tools
    click Ingestion "https://github.com/shyamsridhar123/graphai/blob/main/scripts/load_manybirds_to_cosmos.py"
    click Ingestion "https://github.com/shyamsridhar123/graphai/blob/main/scripts/load_test_data.py"
    click Ingestion "https://github.com/shyamsridhar123/graphai/blob/main/scripts/combine_datasets.py"
    click Ingestion "https://github.com/shyamsridhar123/graphai/blob/main/scripts/generate_enhanced_test_data.py"
    click Ingestion "https://github.com/shyamsridhar123/graphai/blob/main/scripts/production_test.py"
    click Datasets "https://github.com/shyamsridhar123/graphai/blob/main/data/manybirds_products.json"
    click Datasets "https://github.com/shyamsridhar123/graphai/blob/main/data/expanded_manybirds_products.json"
    click Datasets "https://github.com/shyamsridhar123/graphai/blob/main/data/combined_manybirds_dataset.json"
    click Datasets "https://github.com/shyamsridhar123/graphai/blob/main/data/enhanced_manybirds_test_data.json"
    click Documentation "https://github.com/shyamsridhar123/graphai/blob/main/docs/ECOMMERCE_USE_CASE.md"
    click Documentation "https://github.com/shyamsridhar123/graphai/blob/main/docs/COMPELLING_USE_CASE.md"
    click Documentation "https://github.com/shyamsridhar123/graphai/blob/main/docs/TEST_DATA_README.md"
    click Documentation "https://github.com/shyamsridhar123/graphai/blob/main/docs/CLEANUP_SUMMARY.md"
    click Documentation "https://github.com/shyamsridhar123/graphai/blob/main/docs/UV_MIGRATION_SUMMARY.md"
    click Visualization "https://github.com/shyamsridhar123/graphai/blob/main/visualizations/ecommerce_visualization.md"
    click Testing "https://github.com/shyamsridhar123/graphai/blob/main/test_search_enhanced.py"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333;
    classDef business fill:#d4edda,stroke:#333;
    classDef db fill:#ffe5b4,stroke:#333,stroke-width:2px,shape:cylinder;
    classDef cloud fill:#d1ecf1,stroke:#333,shape:cloud;
    classDef config fill:#f8d7da,stroke:#333;
    classDef scripts fill:#fff3cd,stroke:#333;
    classDef data fill:#e2e3e5,stroke:#333;
    classDef docs fill:#f5c6cb,stroke:#333;
    classDef vis fill:#c3e6cb,stroke:#333;
    classDef test fill:#d6d8db,stroke:#333;
```
