# rmn-mann/promtalk architecture

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

- Interactive diagram: https://gitdiagram.com/rmn-mann/promtalk
- Repository: https://github.com/rmn-mann/promtalk

## Overview

##### Project type and purpose
- PromTalk is a lightweight full-stack web application whose goal is to translate natural-language questions into PromQL queries.
- It uses a Python web framework (likely Flask, as suggested by app.py), an LLM backend (Ollama) for translation, and connects to a Prometheus instance for actual metric queries.

##### File structure
- app.py – the main web server entry point; likely defines routes for receiving user input, invoking the LLM, and proxying queries to Prometheus
- requirements.txt – Python dependencies (Flask, Prometheus client, Ollama client, etc.)
- prometheus_metadata_cache.json – a local cache of Prometheus metric metadata (for RAG or quick lookups)
- templates/index.html – frontend HTML template; renders the UI for query input, review/edit, and result display

##### README for additional insights
- Confirms the tech stack: Python (Flask or similar) for frontend/backend, Ollama LLM for translation, Prometheus for metrics
- Lists key features: NL→PromQL translation, query editing, execution, result display
- Mentions future enhancements but does not add new components to the current architecture

a. Main components to include
- User Browser (UI) – sends natural-language queries, displays generated PromQL and results
- Web Server (app.py) – handles HTTP requests, orchestrates calls to LLM and Prometheus
- Ollama LLM Service – an external or local service that runs the language model
- Prometheus Instance – the time-series database that executes PromQL queries
- Metadata Cache – the JSON cache used to supply label and metric hints to the LLM

b. Relationships & data flow
1. User types a question in the Browser → HTTP POST to Web Server
2. Web Server fetches metric metadata (from JSON cache or directly from Prometheus)
3. Web Server sends NL + metadata context to Ollama → receives PromQL
4. Web Server returns the draft PromQL to Browser (user review/edit)
5. Upon user approval, Browser requests execution → Web Server issues PromQL to Prometheus
6. Prometheus returns time-series data → Web Server formats results → Browser displays graphs/tables

c. Architectural patterns & design principles
- Separation of concerns: UI layer, orchestration/business logic, external/third-party services
- MVC-light: templates (View), app.py routes/controllers (Controller), metadata cache & results (Model)
- Caching for performance: local metadata cache to reduce repeated Prometheus calls
- Microservice-style external integrations: Ollama and Prometheus are treated as separate services

d. Key technologies & frameworks
- Python / Flask (or similar) – web framework
- Jinja2 templates – for rendering index.html
- Ollama API – for NL→PromQL translation
- Prometheus HTTP API – for query execution
- JSON cache – for metadata RAG

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["User Browser UI"]:::presentation
        Template["index.html"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        WebServer["Web Server (Flask app)"]:::application
        ReqTxt["requirements.txt"]:::application
        README["README.md"]:::application
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        Ollama["LLM Service – Ollama"]:::integration
        PromAPI["Prometheus HTTP API"]:::integration
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Cache["Metadata Cache (prometheus_metadata_cache.json)"]:::data
        TSDB["Prometheus TSDB"]:::data
    end

    %% Data Flows
    Browser -->|"POST /translate"| WebServer
    WebServer -->|"load metadata"| Cache
    Cache -->|cache hit or miss| WebServer
    WebServer -->|"POST NL+metadata"| Ollama
    Ollama -->|"PromQL"| WebServer
    WebServer -->|"render draft PromQL"| Browser
    Browser -->|"POST /execute PromQL"| WebServer
    WebServer -->|"query TSDB"| PromAPI
    PromAPI -->|"time-series data"| WebServer
    WebServer -->|"formatted results"| Browser

    %% Click Events
    click Template "https://github.com/rmn-mann/promtalk/blob/main/templates/index.html"
    click WebServer "https://github.com/rmn-mann/promtalk/blob/main/app.py"
    click Cache "https://github.com/rmn-mann/promtalk/blob/main/prometheus_metadata_cache.json"
    click ReqTxt "https://github.com/rmn-mann/promtalk/blob/main/requirements.txt"
    click README "https://github.com/rmn-mann/promtalk/blob/main/README.md"

    %% Styles
    classDef presentation fill:#E0F7FA,stroke:#00838F,color:#004D40;
    classDef application fill:#BBDEFB,stroke:#1976D2,color:#0D47A1;
    classDef integration fill:#FFE0B2,stroke:#F57C00,color:#E65100;
    classDef data fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
```
