# yuguerten/plot_keywords architecture

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

- Interactive diagram: https://gitdiagram.com/yuguerten/plot_keywords
- Repository: https://github.com/yuguerten/plot_keywords

## Overview

##### Project type and purpose
- This is a standalone data‐processing and visualization tool (“Keywords Visualization Tool”), not a full‐stack web app. Its sole responsibility is to take a free‐form idea description, extract keywords, embed them in vector space, reduce dimensionality, and render an interactive 2D plot (HTML).

##### File structure
- Top level:
– README.md → project description and pipeline steps
– plot_embbeding.ipynb → Jupyter notebook orchestrating the pipeline and demo
– keywords_2d_plot.html → final interactive output
- No frontend/backend folders; everything lives in one code pipeline.

##### README for additional insights
- Pipeline stages are clearly enumerated:
1. Input description
2. Keyword extraction (Gemini 1.5 Flash)
3. Sentence embeddings (SentenceTransformer)
4. 2D reduction (PCA via scikit‐learn)
5. Plotly‐based plotting
- External service: Google Generative AI (Gemini)
- Core libraries: langchain, sentence-transformers, scikit-learn, plotly, numpy, matplotlib

##### Components & interactions
a. Main components
- Input Module (CLI or Notebook front‐end)
- KeywordExtraction Service (external API call to Google Gemini via google-generativeai, orchestrated by LangChain)
- Embedding Module (SentenceTransformer model running locally)
- DimensionalityReduction Module (PCA via scikit‐learn)
- Visualization Module (Plotly to generate HTML)
- Data artifacts (temporary in-memory vectors; final HTML file)
b. Relationships & dataflow
- Input Module → (user idea) → KeywordExtraction Service
- KeywordExtraction Service → (keywords list) → Embedding Module
- Embedding Module → (high‐dim vectors) → DimensionalityReduction Module
- DimensionalityReduction Module → (2D coords) → Visualization Module
- Visualization Module → (keywords_2d_plot.html) → User browser
c. Architectural patterns & principles
- Pipeline / linear dataflow pattern
- Separation of concerns: each stage is isolated (extraction, embed, reduce, viz)
d. Key technologies/frameworks
- LangChain for orchestration of LLM calls
- google-generativeai for Gemini 1.5 Flash API
- sentence-transformers for embeddings
- scikit-learn PCA for reduction
- Plotly for interactive plotting
- NumPy/Matplotlib for numerical ops and optional static plots

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph for invocation
    subgraph "Jupyter Notebook / CLI"
        Input["Input Module<br>(plot_embbeding.ipynb)"]:::notebook
    end

    %% Documentation
    Doc["Pipeline Documentation<br>(README.md)"]:::doc

    %% External service
    Extraction["Keyword Extraction Service<br>Gemini 1.5 Flash (LangChain)"]:::external

    %% Local processing modules
    Embedding["Embedding Module<br>SentenceTransformer"]:::module
    Reduction["Dimensionality Reduction Module<br>PCA (scikit-learn)"]:::module
    Visualization["Visualization Module<br>Plotly"]:::module

    %% Data artifacts
    Vectors["In-Memory Vectors"]:::artifact
    HTML["Final Output HTML<br>(keywords_2d_plot.html)"]:::artifact

    %% Data flow
    Input -->|"idea description"| Extraction
    Extraction -->|"keywords list"| Embedding
    Embedding -->|"high-dimensional embeddings"| Vectors
    Vectors -->|"2D coordinates"| Reduction
    Reduction --> Visualization
    Visualization -->|"HTML file"| HTML

    %% Documentation linkage
    Doc -.-> Input

    %% Click events
    click Input "https://github.com/yuguerten/plot_keywords/blob/master/plot_embbeding.ipynb"
    click Extraction "https://github.com/yuguerten/plot_keywords/blob/master/plot_embbeding.ipynb"
    click Embedding "https://github.com/yuguerten/plot_keywords/blob/master/plot_embbeding.ipynb"
    click Reduction "https://github.com/yuguerten/plot_keywords/blob/master/plot_embbeding.ipynb"
    click Visualization "https://github.com/yuguerten/plot_keywords/blob/master/keywords_2d_plot.html"
    click Doc "https://github.com/yuguerten/plot_keywords/blob/master/README.md"

    %% Styling
    classDef notebook fill:#FFD97D,stroke:#333,stroke-width:2px
    classDef external fill:#8ED1FC,stroke:#333,stroke-width:2px
    classDef module fill:#A0E7A0,stroke:#333,stroke-width:2px
    classDef artifact fill:#F4A7B9,stroke:#333,stroke-width:2px
    classDef doc fill:#CCCCCC,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
```
